Webhooks

Webhooks are a way for your application to get real-time data from our API. They are a form of reverse API that gives you the ability to collect information as it happens, rather than making API calls

Setting up Webhooks

To set up a webhook, you need to provide a URL in your application where our API can send HTTP POST requests. This URL is known as your webhook endpoint.

The Webhooks configuration can be found on the API Integration page.

Webhooks Events

Our application will send a POST request to your webhook endpoint every time an event happens in your account. The body of this POST request contains all the relevant information about the event.

All events that include the evaluation property will contain the following information:

• type - can be kyc, fraud, or document

• status - can be initiated, in_progress, completed, or failed

Currently, we support the following webhook events:

• onboard: This event is triggered when a customer is approved or rejected on Waldo dashboard.

Data sample for the onboard event received by your server

{
    "requestId": "ayclpQyi6p",
    "event": "onboard", 
    "evaluation": {
        "type": "fraud",
        "status": "initiated"
    },
    "validation": {
        "status": "REVIEW",
        "kyc": "PENDING",
        "fraudScore": 0
    },
    "externalId": "abcd-123-456-efgh",
    "customerId": "650c3ebe44aa0043cc846755",
    "uri": "https://app.waldo.ai/customers/650c3ebe44aa0043cc846755"
}

• flag: This event is triggered when a customer is flagged or unflagged as fraud risk on Waldo dashboard.

Data sample for the flag event received by your server

{
    "event": "flag", 
    "flag": true,
    "externalId": "abcd-123-456-efgh",
    "customerId": "<customer-id>",
    "uri": "https://app.waldo.ai/customers/<customer-id>"
}

• evaluation: This event is triggered when an evaluation is requested via either the dashboard, or the API.

Data sample for the evaluation event received by your server

{
  "requestId": "ayclpQyi6p",
  "event": "evaluation",
  "evaluation": {
    "type": "fraud",
    "status": "initiated"
  },
  "validation": {
    "status": "REVIEW",
    "kyc": "PASSED",
    "fraudScore": 0
  },
  "externalId": "abcd-123-456-efgh",
  "customerId": "650c3ebe44aa0043cc846755",
  "uri": "https://app.waldo.ai/customers/650c3ebe44aa0043cc846755"
}

Testing your Webhooks

When setting up the webhooks on Waldo dashboard, you will find a tool to test the integration.

Preventing webhook loops

Waldo's service can be used from the dashboard, and the API as well. To handle properly the incoming data in the webhooks, please track the property requestId.

When an operation is executed from the dashboard, the webhooks will receive a notification. This notification will not contain the requestId, therefore your system should process, if useful, this information.

When an operation is requested via the API, the response from Waldo will contain the requestId property. All subsequent notifications related to this request will include the requestId previously sent back. From this point, use the requestId to update your system, if needed.

Webhooks Security Configuration

To ensure the security of webhook notifications, we use HMAC (Hash-based Message Authentication Code) to sign the payloads. This allows webhook consumers to verify the authenticity of the requests.

For this you will need the webhooks secret you have used in the webhooks configuration page.

Verifying the Webhook Signature

When your endpoint receives a webhook notification from Waldo, it will include a custom header X-Waldo-Signature. This header contains the HMAC signature of the payload. You should use this signature to verify the request.

Here is a step-by-step guide to verify the webhook signature:

1. Extract the Signature: Retrieve the X-Waldo-Signature header from the request

2. Compute the HMAC: Use the same secret key that was used to sign the payload to compute the HMAC of the received payload.

3. Compare Signatures: Compare the computed HMAC with the X-Waldo-Signature header. If they match, the request is verified.

Below is an example in JavaScript using Node.js to verify the webhook signature:

import crypto from 'crypto';

/**
 * Verifies if the provided HMAC signature matches the calculated signature for the given payload.
 * 
 * @param {Object} payload - The payload to be signed.
 * @param {string} secret - The secret key provided in the webhooks configuration.
 * @param {string} signature - The HMAC signature (X-Waldo-Signature header) to verify.
 * @returns {boolean} - Returns true if the signatures match, otherwise false.
 */
 
const isAuthorized = (payload, secret, signature) => {
    const hmac = crypto.createHmac('sha256', secret);
    hmac.update(JSON.stringify(payload));
    const calculatedSignature = hmac.digest('hex');
    return calculatedSignature === signature;
};