Overview
Trulioo utilizes HMAC (Hash-based Message Authentication Code) to authenticate webhook events, ensuring that they are genuinely sent from Trulioo. Each sent to you will include an HMAC signature in the `x-trulioo-signature` header. This HMAC signature is generated using a secret key shared by Trulioo's team. You can use signature to confirm the authenticity of the event.
Steps to Implement HMAC Authentication
1. Generate a Token
Generate an authentication token by calling the following endpoint with your `clientId` and `clientSecret`.
curl -X POST "https://auth-api-primary.dev.trulioo.com/connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=<your-client-id>&client_secret=<your-client-secret>&grant_type=client_credentials"
2. Retrieve Webhook Credentials
Retrieve the current webhook credentials needed for generating HMAC by calling the endpoint below and passing the token generated in the previous step.
curl -X GET "https://auth-api-primary.dev.trulioo.com/api/v2/client-webhooks/current-credential?AccountIdentifier=6f87470e-67d-497a-a787-abab4d437dff" \
-H "Authorization: Bearer <your-access-token>"
Response Schema:
{
"data": {
"accountIdentifier": "6f87470e-eflk5-497a-a787-abarwerf4d437dff",
"webhooks": [
{
"webhookIdentifier": "8c45063c-998a-4b4c-aaf2-9efg8891a0082f",
"webhookCallbackUrl": null,
"credentials": [
{
"credentialIdentifier": "35fd3bc3-672f-4474-86de-bd905687d580b4",
"secretValue": "l1U^g#FIZ1MZ=lLG3107UmuaZ-6B_3i435261V00EF65ZAttlcH$Re?@44#M3-",
"effectiveStartDateTimeUTC": "2023-06-21T00:00:00",
"expirationDateTimeUTC": "2024-04-19T13:30:00"
}
]
}
]
}
}
secretValue
The secretValue is the key used to generate and validate the HMAC signature. The HMAC secret used in steps 1 and 2 can be obtained by contacting your Trulioo team at [email protected]
3. Compute and Add HMAC Signature
Compute the SHA256 HMAC using the event payload and the retrieved **secretValue** for each webhook event sent to the you,. Add this computed HMAC to the **x-trulioo-signature** header of the request.
4. Customer Verification of HMAC Signature
You should decode the **x-trulioo-signature** using the **secretValue** obtained from Trulioo team. The decoded hash should match the actual payload sent by Trulioo. If the values do not match, the customer should reject the request.