Webhook

Trulioo provides webhooks to alert you of changes in the status of your transaction. These are POST requests to your server that are sent as soon as an event occurs. The body of the request contains details of the event.

Your endpoint must be an HTTPS webhook address with a valid SSL certificate that can correctly process event notifications.

Webhook Security

Once your server is configured to receive payloads, it'll listen for any payload sent to the endpoint you configured. For security reasons, you probably want to limit requests to those coming from Trulioo. There are a few ways to go about this (for example, you could opt to allow requests from Trulioo's IP address) but a far easier method is to set up a secret token and validate the information.

1. On secure webhook requests, the Trulioo signs the webhook message using the secret key plus HMAC-SHA256 hashing algorithim to encode using hex, and will include the signature in the webhook request as a header x-trulioo-signature.

2. The webhook listener receives the request and repeats the same steps — signs and encodes the webhook message using the secret key — and compares the resulting signature with the value sent in the request header. If the result matches, the request is considered legitimate.

Webhook Object

During a standard workflow, the webhook will receive event updates that will indicate the status of the transaction. Events are used to gather deeper insight into the process. At this time you cannot unsubscribe from any particular events

POST

Webhook will need to accept a POST request at given url with the follow contract structure.

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

Events

An event provides insight into the status and result of a transaction. PII is not emitted through an event or webhook and thus upon completion of a transaction you will need to request the transaction details for further insights.

NOTE: When using the Customer API only without our SDK, only the following events will be sent: create, image_processing, decision, abandon

Retry logic
Upon receiving a webhook notification, you should acknowledge success by responding with an HTTP 20x response within 10 seconds.

Duplicate events
We guarantee at-least-once delivery of webhooks, which means that in rare occasions you may receive duplicate events. You should treat events as idempotent to avoid unwanted effects in your application.

Ordering
Trulioo doesn't guarantee order when delivering events. As a result, you may receive an event before another event that was created earlier. You should expect to receive them out of order and handle them accordingly.