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

(optional)
dwn-profiling: <profileBlob>
request-id: <request.identifier> or <profiling.cloud_front.request_id>
from-identifier: <identifier>
from-identifier-timeout: 1000

Optional headers:

• dwn-profiling: <profileBlob> direct protobuff blob collected from profiling.  

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

Following headers are only used if retrieving an event in process or already processed:

• request-id:  If The request.identifier value OR profiling.cloud_front.request_id of event to retrieve

  • Example: e7f2f281ada45708b889f02bd85afb

• from-identifier:  The identifier value of event to retrieve

  • Example: 73dcdde8a91e4d1698ba4cf50503f9a1

  • Will return error if request-id + from-identifier combination not present on event within last 24h.

• from-identifier-timeout:  Maximum time in milliseconds to wait for Darwinium processing, before returning response.

  • Default value: 1000

  • If reaching timeout, it will return all data available at that time in response.

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

Follow best practices!

Calling the Darwinium API should follow ‘fail-open’ practices.
Any scenario that is not receiving the risk assessment response attribute should be passed by default

That may include:

• Too long to respond; use a timeout (eg. 3s)

• Receiving an error from the API

• The attribute being used to decision is not in the response body

• The attribute being used to decision is not in expected format

Request Body

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

{
    "primary_session_tie": "mytestsessiontoken12345",
    "organization": {
        "application_name": "myretailappv1",
        "event_type": "retail_payment",
        "line_of_business": "retail"
    },
    "identity": {
        "ACCOUNT": {
            "email": {
                "PERSONAL": {
                    "email": "test@test.com"
                }
            },
            "customer_token": {
                "customer_token": "testcustomerlogin"
            },
            "login": {
                "login": "testcustomerlogin"
            },
            "telephone": {
                "MOBILE": {
                    "e164_number": "+18004444444"
                }
            }
        }
    },
    "payment": {
        "amount": 100,
        "currency": "USD",
        "reference_number": "testreferenceid"
    },
    "custom_identifier": {
        "CUSTOM_IDENTIFIER_1": {
            "identifier": "testcustomidentifier1"
        }
    },
    "custom": {
        "general_purpose":{
            "test_attribute": "include any extra data",
            "can_use_any_name_here": "only available on this event"
        }
    }
}

All request body attributes are optional

There are no mandatory attributes. An empty request body is valid {}.

Attributes not expected at a step can just be removed from the request body.

But it is suggested to include input attributes for:

• additional context that can help make better risk assessments

• provide better partitioning to your fraud analysts when searching and analysing events

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)

{
    "journey_name": "authjourney",
    "step_name": "payment",
    "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": {
                    "payment.bot": -50.0,
                    "payment.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": [
                    "REJECT"
                ]
            }
        }
    },
    "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

To perform API call risk assessment within context of a journey that is already initiated, a journey_id or primary_session_tie is a required input in request body. The event will appear as another action and row of data within that existing journey, with opportunity to import dependencies from previous steps in the journey as per usual.

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.

It is best used when previous steps can be assumed to be already processed (after ~4 seconds), as there is no waiting of dependencies. If previous event of interest in journey has not finished processing, that data will simply not be available.

Event data from same journey_id is only available for 12h.

Supplying journey_id or primary_session_tie(s) in request body

• journey_id:  The Darwinium created identifier for the session. Resolved Darwinium side and considers the values of both the journey cookie and session ties.

{
    "journey_id": "dab65233586540188d1112e999556701"
}

• primary_session_tie: Input attribute which can be an existing JWT or web session token that your application already generates and uses to track sessions.

  • Matching session_tie values will resolve to the same Darwinium journey_id

  • secondary_session_tie and tertiary_session_tie also exist to support resolving from multiple potential identifiers.

{
    "primary_session_tie": "mysessiontoken12345",
    "secondary_session_tie": "myothersessiontoken6789"
}

Session tie scoping and replacement

primary_session_tie and secondary session tie are individually scoped. Meaning primary_session_tie will only be compared against primary_session_tie.

If you want to refresh/replace a session-tie using the API, calling the API twice (once with the old tie, once with the new) and passing journey_id in the request body to connect them.

Example Process: Edge Worker providing journey_id in header

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 an event (possibly being) processed

Use this approach if the aim is to call the Darwinium API Step to retrieve details of an event, that is expected to either:

• Be in process

• Be very recently processed

The approach includes a wait for the dependencies needed to finish before returning response, but may return a limited subset of a full response schema.

Headers

Content-Type: application/json
Accept: application/json
request-id: <request.identifier> or <profiling.cloud_front.request_id>
from-identifier: <identifier>

(optional)
from-identifier-timeout: 1000

• request-id:  The request.identifier value OR profiling.cloud_front.request_id of event to retrieve

  • Example: e7f2f281ada45708b889f02bd85afb

• from-identifier:  The identifier value of event to retrieve

  • Example: 73dcdde8a91e4d1698ba4cf50503f9a1

  • Will return error if request-id + from-identifier combination not present on event within last 24h.

• from-identifier-timeout:  Maximum time in milliseconds to wait for Darwinium processing, before returning response.

  • Default value: 1000

  • If reaching timeout, it will return all data available at that time in response.

Use Cases

It is best used when:

• Event is being processed: API call is initiated from your back-end, on same request as Edge step event processed

  • Example: DWN edge step worker configured on a /register endpoint. But backend origin calls the DWN API upon processing register request too

  • Response dependencies cannot be set under this design pattern, as by definition the API is being called in the middle of the flow, before the response is returned

• Avoid race condition: The API call is expected very soon after the event of interest is processed

  • Why?: This method actively waits for processing of the event if not yet finished.

  • The maximum acceptable Darwinium processing wait time can be specified in from-identifier-timeout header

  • It will return all data processed up to that time.

Example Process: Edge Worker + Event Retrieve

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

Inserting Headers Consideration

When inserting headers, consult your web development team to ensure security policies will expect and permit them

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 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