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.