Events Reference

Payload Format

Each webhook is an HTTPS POST request containing a JSON payload and a signature header.

Header:

X-DLT-Signature: dupyAbK5Z2vB7cNHN5pu7voGKPANyjyM/g...==
Content-Type: application/json

Body:

{
  "notification_id": "8e9b9a45-6212-4a77-bb43-4b8d123a5e42",
  "created_at": "2024-10-29T12:15:42Z",
  "owner_id": "8e9b9a45-6212-4a77-bb43-4b8d123a5e42",
  "owner_type": "person",
  "external_id": "client_id_123",
  "entitlement_trigger_id": "8e9b9a45-6212-4a77-bb43-4b8d123a5e42",
  "entitlement_id": "9a9b9a45-6212-4a77-bb43-4b8d123a5e42",
  "notification_type": "requirementsQuestionnaire",
  "details": {
     // Event specific data
  }
}

Workflow Events

Webhook events are tied to specific workflows. The notification_type and its associated details payload vary depending on the active workflow.

1. Onboarding

This workflow covers the onboarding of Persons (KYC Onboarding - standard or reliance flow) and Corporates (KYB Onboarding). Each event notes which onboarding flows it applies to.

requirementsQuestionnaire - all onboarding flows. Triggered when one or more questionnaires must be completed. In KYB Onboarding, it is also emitted for questionnaires assigned to the corporate's linked Individuals.
```
{
  "notification_type": "requirementsQuestionnaire",
  "details": {
    "pending_questionnaire_ids": ["3cb3bdae-96eb-4097-9cc1-01c4fcf911ca"],
    "reason": "onboarding"
  }
}
```

entitlementCompleted - all onboarding flows. Emitted when onboarding is successful. Includes risk assessment results.

{
  "notification_type": "entitlementCompleted",
  "details": {
    "riskScore": 15,
    "pep": false,
    "criminal": false,
    "sanctioned": false,
    "adverse_media": false
  }
}

entitlementFailed - all onboarding flows. Emitted when onboarding fails. The details contain either an error code with a description (see the Error Codes Reference) or a plain-text reason.

Standard flow example (IDV-related codes occur only in the standard flow):
```
{
  "notification_type": "entitlementFailed",
  "details": {
    "code": "FL0001",
    "description": "Unacceptable IDV risk"
  }
}
```
Role-structure, screening, and risk failures arrive as a reason instead - see the KYB failure reasons:
```
{
  "notification_type": "entitlementFailed",
  "details": {
    "reason": "Corporate is sanctioned"
  }
}
```
kycCheckPassed - setup-dependent. Emitted once all compliance checks have passed, before the account setup completes. Sent only for integrations where the custody integration applies; whether your setup receives it is part of your entitlement configuration.
```
{
  "notification_type": "kycCheckPassed",
  "details": {}
}
```

Identity Verification (IDV) - standard retail flow only

The IDV events are sent only in the standard flow of KYC Onboarding. They are never sent in the reliance flow, and not currently in KYB Onboarding (a standard KYB variant is in development).

requirementsIDV: Triggered when an Identity Verification session needs to be started by the user.

{
  "notification_type": "requirementsIDV",
  "details": {
    "workflow_id": "44907951-1825-4a91-b1c8-f84d708a22e3",
    "branch": "DEU",
    "name": "IDVandQESandBAV"
  }
}

completedIDV / failedIDV / errorIDV: Status updates for the IDV process.

{
  "notification_type": "completedIDV",
  "details": {
    "status": "success",
    "messages": [
      { "timestamp": "2024-09-03T14:55:26Z", "statusCode": 200, "description": "Verification successful" }
    ]
  }
}

2. AdHoc Enhanced Due Diligence (EDD)

Triggered when additional checks or locks are dynamically applied to an existing user's account.

entitlementStarted: Indicates the AdHoc EDD process has begun.

{
  "notification_type": "entitlementStarted",
  "details": {
    "description": "Retail AdHoc EDD entitlement started"
  }
}

entitlementCompleted: The EDD check passed. Includes final lock status.

{
  "notification_type": "entitlementCompleted",
  "details": {
    "outcome": "passed"
  }
}

entitlementFailed: The EDD check failed. Includes final lock status.

{
  "notification_type": "entitlementFailed",
  "details": {
    "outcome": "failed"
  }
}

3. Proof of Source of Funds (POSOF)

Workflows to verify a user's source of funds at various tiers (Level 1, 2, 3).

requirementsQuestionnaire: Requests the user to fill out specific POSOF questionnaires.

entitlementCompleted: Emitted when POSOF requirements are satisfied. Includes the achieved tier.

{
  "notification_type": "entitlementCompleted",
  "details": {
    "posof_level": "Level 2"
  }
}

entitlementFailed: Emitted when the user fails the POSOF check. Note that a rejected Corporate PoSoF review instead arrives as entitlementCompleted with "posof_upgraded": "Rejected" and "posof_level": null.

4. Derivatives

Workflows for granting access to derivatives trading (Qualified Retail, Professional by Request).

requirementsQuestionnaire: Usually requests the "Appropriateness Test".

entitlementCompleted: The user is granted access to derivatives.

{
  "notification_type": "entitlementCompleted",
  "details": {}
}

entitlementFailed (Standard): User is denied. Includes a code and description. See the Error Codes Reference for details.

{
  "notification_type": "entitlementFailed",
  "details": {
    "code": "R0003",
    "description": "Acknowledgements Verification Failed"
  }
}

entitlementFailed (Blacklist): Sent when a user is temporarily locked from derivatives due to failure in the appropriateness test.

{
  "notification_type": "entitlementFailed",
  "details": {
    "code": "retailDerivatives30DaysBlacklist",
    "description": "User failed Appropriateness test. Locking from entitlement for 30 days",
    "lock_date": "2024-10-29",
    "lock_release_date": "2024-11-28"
  }
}

5. Request for Information (RFI)

Workflows for manual information gathering and document requests from users.

entitlementStarted: Indicates the RFI process has begun.

{
  "notification_type": "entitlementStarted",
  "details": {
    "description": "Retail Request for Information entitlement started"
  }
}

requirementsQuestionnaire: Requests the user to provide specific information or documents.

{
  "notification_type": "requirementsQuestionnaire",
  "details": {
    "pending_questionnaire_ids": ["3cb3bdae-96eb-4097-9cc1-01c4fcf911ca"],
    "reason": "request_for_information"
  }
}

reminder: Sent when a user has pending requirements that need attention.

{
  "notification_type": "reminder",
  "details": {
    "type": "rfi_2_week_reminder"
  }
}

{
  "notification_type": "reminder",
  "details": {
    "type": "rfi_4_week_reminder"
  }
}

entitlementCompleted: The RFI check passed. Includes final lock status.

{
  "notification_type": "entitlementCompleted",
  "details": {
    "outcome": "passed"
  }
}

6. Account Locks

These standalone events indicate changes to account lock states. They are often emitted as side effects of other workflows (like AdHoc EDD or RFI).

applyTradingLock / releaseTradingLock
applyFundingLock / releaseFundingLock
applyWithdrawalLock / releaseWithdrawalLock

Payload Example:

{
  "notification_type": "applyFundingLock",
  "details": {}
}

Payload Format​

Workflow Events​

1. Onboarding​

Identity Verification (IDV) - standard retail flow only​

2. AdHoc Enhanced Due Diligence (EDD)​

3. Proof of Source of Funds (POSOF)​

4. Derivatives​

5. Request for Information (RFI)​

6. Account Locks​