Device Intelligence Webhook

Trulioo provides webhooks to notify you when device intelligence processing completes and when a device intelligence decision is available. These are POST requests sent to your configured webhook URL as soon as an event occurs. The request body contains details about the event.

You can configure webhooks for live, sandbox, or both environments.

Retry logic

Upon receiving a webhook notification, acknowledge it by responding with an HTTP 20x response within 10 seconds. Trulioo automatically retries HTTP 5xx responses up to three times using exponential backoff. HTTP 4xx responses are not retried.

Duplicate events

Webhook delivery is at least once, so you may occasionally receive duplicate events. Process events idempotently to avoid unwanted effects in your application.

Ordering

Trulioo does not guarantee event delivery order. An event may arrive before another event that was created earlier. Your application should handle events arriving out of order.

Webhook object

The webhook object identifies the transaction and describes the device intelligence event. Personally identifiable information (PII) is not included in the webhook. Retrieve the transaction details separately when additional information is required.

Attribute	Type	Description
id	String	Unique identifier for the webhook.
transactionId	String	Transaction identifier used to retrieve status details and verification results.
clientId	String	Optional external identifier associated with the transaction.
event	Object	Event containing the name, type, and result.
error	Object	Error containing the standard numeric code and message.

Device intelligence events

Name	Type	Result	Description
device_intelligence	transaction	completed	Device intelligence processing completed. This event does not communicate the device decision.
device_intelligence_decision	transaction	accepted, review, declined, error, or no_result	A device-scoped decision or advisory is available.

For a device-only flow, device_intelligence_decision communicates the terminal verdict instead of the general decision event.

For a mixed document and device flow, device_intelligence_decision communicates the device advisory. The final transaction-wide verdict is delivered separately in the general decision event.

POST

Your webhook URL must accept a POST request with the following contract structure:

{
  "id": "",
  "transactionId": "",
  "clientId": "",
  "event": {
    "name": "",
    "type": "",
    "result": ""
  },
  "error": {
    "code": 0,
    "message": ""
  }
}

Device intelligence processing-completion example:

{
  "id": "0c2f4df3-74b5-4eed-b248-4d93c14d9a54",
  "transactionId": "7d0cb43f-6ce1-43ea-aa67-3d84d4348012",
  "clientId": "your-client-id",
  "event": {
    "name": "device_intelligence",
    "type": "transaction",
    "result": "completed"
  },
  "error": {
    "code": 0,
    "message": ""
  }
}

Device intelligence decision example:

{
  "id": "5c733b35-15d4-42ba-89bb-b2354f6e62c7",
  "transactionId": "7d0cb43f-6ce1-43ea-aa67-3d84d4348012",
  "clientId": "your-client-id",
  "event": {
    "name": "device_intelligence_decision",
    "type": "transaction",
    "result": "accepted"
  },
  "error": {
    "code": 0,
    "message": ""
  }
}