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.

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

ATTRIBUTE	Type	DESCRIPTION
id	String	The identifier for the webhook
transactionId	String	Transaction Id that can be used to follow up on status details and verification results
clientId	String	Optional paramater used to sync external identifier
event	Object	Event object containing information on the status of the transaction workflow
error	Object	Error object that will follow standard format of Code & Message

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

Name	Type	Result	Error Code	Error Message
`create`	transaction	`created`	1101	Error creating transaction
`submit`	transaction	`submitted`	1102	Error submitting transaction
`decision`	transaction	`accepted` \| `review` \| `declined`	1103	Error getting transaction decision
`abandon`	transaction	`abandoned`	1104	Error on abandoned transaction
`re_verification`	transaction	`started` \| `completed`	1105	Error on reverification transaction
`document_verification`	transaction	`manual`	1106	Error on document verification transaction
`facematch`	transaction	`manual`	1107	Error on facematch transaction
`desktop_to_mobile`	step	`started` \| `completed` \| `restarted` \| `error`	1201	Error on desktop to mobile step type
`biometric_policy`	step	`started` \| `completed` \| `error`	1202	Error on biometric policy step type
`welcome`	step	`started` \| `completed` \| `error`	1203	Error on welcome step type
`document_select`	step step_metadata	`started` \| `completed` \| `canceled` \| `error` `user_action_document_selection: <document type>`	1204	Error on document select step type
`jurisdiction_select`	step step_metadata	`started` \| `completed` \| `canceled` \| `error` `user_action_jurisdiction_country_selection: <country>` `user_action_jurisdiction_selection`	1205	Error on jurisdiction step type
`document_front`	step step_metadata	`started` \| `completed` \| `error` `document_device_camera_resolution: <width: 1920p x height: 1080p>`	1206	Error on document front step type
`document_back`	step step_metadata	`started` \| `completed` \| `error` `document_device_camera_resolution: <width: 1920p x height: 1080p>`	1207	Error on document back step type
`selfie`	step step_metadata	`started` \| `completed` \| `error` `document_device_camera_resolution: <width: 1920p x height: 1080p>`	1208	Error on selfie step type
`verification`	step	`started` \| `completed` \| `error`	1209	Error on verification step type
`introduction`	step	`started` \| `completed` \| `error`	1210	Error on introduction step type
`country_select`	step step_metadata	`started` \| `completed` \| `canceled` \| `error` `user_action_country_selection`	1211	Error on country select step type
`done`	step	`started` \| `completed` \| `error`	1212	Error on done step type
`other_document_select`	step step_metadata	`started` \| `completed` \| `canceled` \| `error` `user_action_document_selection: <document type>`	1213	Error on other document select step type
`camera_denied`	step	`started` \| `completed` \| `error`	1214	Error on camera denied step type
`document_instruction`	step	`started` \| `completed` \| `canceled` \| `error`	1215	Error on document instruction step type
`selfie_instruction`	step	`started` \| `completed` \| `canceled` \| `error`	1216	Error on selfie instruction step type
`unknown`	step_metadata unrecognized	`started` \| `completed` \| `restarted` \| `canceled` \| `no_result` \| `error`	1100	Unknown error
`image_processing`	image	`error`	1217	Image type must be one of: PNG, JPG, JPEG, TIFF, BMP, GIF, PDF, WEBP
`image_processing`	image	`error`	1218	Image cannot be correctly converted
`image_processing`	image	`error`	1219	PDF is password protected
`image_processing`	image	`error`	1220	Error extracting images from PDF

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.