Calling the Event API

The Darwinium Event API allows processing of an end user action (‘event’) through the Darwinium decision engine directly.

Your back end performs the API call to a Darwinium API step and receives back the Darwinium risk assessment data in response body.

The call to Darwinium API will often include the profileBlob, collected with Javascript or SDK profiling sent on regular API request, as header: dwn-profiling.

Use cases for the Darwinium Event API include:

1. To perform risk assessment and receive back full Darwinium event data in the API response body

   1. for real-time decisioning and action

   2. for storing the data to analyse

2. To perform the risk assessment considering additional input data that is only available at your origin.

3. To perform risk assessment of offline events; those without a digital interaction. Those events can then be remembered for subsequent customer interactions. Examples: call centre, kiosk, branch, phone channels.

4. To retrieve the risk assessment data of an event Darwinium has already processed.

Authentication

The Event API uses certificates as authentication (Mutual TLS), rather than API keys.

Follow self-serve certificate signing process to obtain:

1. Private key that you generate and upload to Darwinium Portal

2. Darwinium certificate (signed) that you subsequently download from Darwinium Portal

The private key and Darwinium certificate should be used on all API calls for authentication.

Creating a Darwinium API Step

You create and deploy the Darwinium API Step from your Darwinium journey file.

To create an API step, open your journey in Workflows of Darwinium Portal, click the dropdown next to the "+" button on the journey step overview:

Then configure the API step:

• Step Name:

  • A name that best represents this user action. eg. login

• Journey Name

  • Set under Configuration if not done so already

• Event Type

  • From predefined list. Important for feature calculations to partition previous events

• (optional) Step Description

• (optional) Import dependencies:

  • The data from dependencies will be inherited into the step and response. Used for import precomputed scores and signals.

• (optional) Workflows:

  • Features, Rulesets and Models can be added just like any other step.

Make sure to commit and deploy the changes to the journey.

Calling the Event API

Now the Event API step can be called.

Authentication

A valid client certificate that has been configured with access to your node.
See : Setting up certificates & Access

Headers

Content-Type: application/json
Accept: application/json
dwn-profiling: <profileBlob>
from_identifier: <identifier>
request-id: <request.identifier>

Optional headers:

• dwn-profiling: direct protobuff blob collected from profiling.  

  • Example: This can be up to ~8kb: 2AOo3KL…..…jdsDI=

• from_identifier:  The identifier value if retrieving an event already processed.

  • Example: 73dcdde8a91e4d1698ba4cf50503f9a1

• request-id:  The request.identifier value if retrieving an event already processed.

  • Example: e7f2f281ada45708b889f02bd85afb

URL

POST request to:

https://<example>-<host>.node.darwinidentity.com:9443/<journey>/<step>

• <example>-<host>: This is the two random words assigned to your node's subdomain. They can be retrieved from Darwinium Portal > Admin > Nodes.

• <journey>: This is the journey_name specified in configuration of your deployed in .journey.yaml file. Note this can be different to the name of the file.

• <step>: This is the step_name of the API step you created and deployed in .journey.yaml file.

An example URL might look like

https://random-words.node.darwinidentity.com:9443/authjourney/login

Request Body

The request POST body consists of a JSON hierarchy of the attributes you wish to add as context to the risk assessment

Request Body example:

{
  "identity": {
    "ACCOUNT": {
      "email": {
        "PERSONAL": {
          "email": "test@test.com"
        }
      }
    }
  }
}

Response Body

The response body takes same JSON format, but additionally includes:

• Real time risk assessment attributes (eg. signals, model scores, decision strategy results)

• Darwinium profiling attributes & enrichment (eg. device identifier, signature, IP address, IP geolocation)

Response Body example:

{
    "journey_name": "authjourney",
    "step_name": "login",
    "identifier": "2cb7594d12ec4378ac03be04cad971f0",
    "timestamp": "2025-03-17T12:57:28.962+00:00",
    "request": {
        "identifier": "38820db1bce14bdd8a82d856eed76498",
        "timestamp": "2025-03-17T12:57:28.962+00:00"
    },
    "outcome": {
        "CHAMPION": {
            "features": {
                "general": {
                    "cnt_dist_device_same_custid": 1.0,
                    "timesince_nao": 15000
                }
            },
            "models": {
                "score": {
                    "login.bot": -50.0,
                    "login.account_takeover": -912.0

                },
                "signals": [
                    "New Device",
                    "IP not seen before",
                    "Script automation"
                ]
            },
            "decision_strategy": {
                "result": "reject",
                "score": -400.0,
                "signals": [
                    "Account Takeover Risk"
                ],
                "signal_categories": [
                    "Account Takeover"
                ]
            }
        }
    },
    "profiling": {
        "handle": "dbd1150b08a942b9bf241619b4e4c9d2",
        "tcp_connection": {
            "PRIMARY": {
                "ip_address": "192.168.1.1",
                "ipinfo": {
                    "latitude": -33.86785,
                    "longitude": 151.20732,
                    "city": "Sydney",
                    "country": "AU",
                    "asn": "AS4764"
                    }
                }
            },
        "device": {
            "identifier": "81212d1b084d4aea841752d2c5b36b8e",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:137.0) Gecko/20100101 Firefox/137.0",
            "signals": [
                "CREDENTIAL_AUTOMATION"
            ]
        },
        "javascript": {
            "os": "Mac OS X",
            "browser": "Firefox",
            "os_version": "10.15",
            "browser_version": "137",
            "key_biometrics": {
                "FULL_NAME": {
                    "type": "text",
                    "name": "toname",
                    "element_id": "id_toname",
                    "auto_fill": 1
                }
            },
            "mouse_biometrics": {
                "mouse_off_screen": 3,
                "time_off_screen": 3791,
                "num_strokes": 20,
                "left_click": 5,
                "stroke": {
                    "DISTANCE": {
                        "min": 9.0,
                        "max": 311.6591796875,
                        "avg": 93.54168701171875,
                        "median": 67.07205963134766,
                        "std_dev": 76.77576446533203,
                        "mad": 45.780757904052734
                    }
                }
            }
        }
    },
    "device_signature": {
        "VER_1": {
            "identifier": "c5f9f9e4c6e74cb88932c3b69a10a048",
            "probability": 0.99
        }
    }
}

Full Schema: Request/Response Body

• The Darwinium API Helper can assist with the format of this JSON for the attributes you wish to include.

• The following endpoint returns full Darwinium API schema as a collection: /api/schema

• See also Attribute reference

Using the Darwinium API Helper

As a convenience, the Darwinium journey editor provides a means of quickly assembling API calls in the required format. Simply click Help me construct an API call to this step on the Step Summary tab of an API step, and a new tab should appear with your steps details completed. You are then able to select which attribute(s) you wish to input as part of your API call. Boilerplate is then generated with mock values for each input which can then be used by your integration.

Calling the Event API: to continue an existing journey

A journey_id or primary_session_tie is a required input in top level of request body to perform risk assessment within context of a journey that is already initiated. The event will appear as an action within that journey.

• journey_id:  The Darwinium created identifier for the session. Considers values of journey cookie and session ties.

• primary_session_tie: Input attribute which can be an existing JWT or web session token for example, The Darwinium journey_id will resolve to be the same for events with the same session tie(s).

Why do this?: Using an API step allows a risk assessment which includes data attributes only present at your origin, not in the request layer.

Retrieving journey_id

If needing the journey_id and using Proxy (Edge) Steps, a useful approach is adding the Darwinium journey_id as a header on existing requests to your downstream service within the previous Darwinium steps up to this one.

Calling the Event API: to retrieve event already processed

If your aim is to call the Darwinium API Step to retrieve details of a previous event you must have headers:

from-identifier: <identifier>
request-id: <request.identifier>

These headers can be injected by a Darwinium edge worker on an upstream request and passed to your backend.

These values are then used in the subsequent calls made from your origin to the Darwinium API step.
This approach does not require dependencies to be imported. You’ll have the option to insert decision strategies or rules to your API step if your desire is to calculate risk scores or invoke a decision for example.

No request body is required in the Event API call when mapping the attributes using this method.

This curl request in this example returns the event with the matching request-id and identifier from the original request made to your CDN

curl --location 'https://YOUR-HOST.node.darwinidentity.com:9443/api/event/example/api_step' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'from-identifier: 73dcdde8a91e4d1698ba4cf50503f9a1' \
--header 'request-id: e7f2f281ada45708b889f02bd85afb' \
--data '{}'

The response will return an object containing all of the events details just as if you were to query it from the UI

Example Code: Calling the Event API

 Example API Code