HMAC

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.