Skip to main content

Webhooks in Detail

In order to understand the Webhooks available to users, it is helpful to discuss how the platform generally works and provide some insights.

The Platform​

We use an Event Driven Architecture (EDA) to handle the events that happen in the platform. There are many events that are triggered by different actions, and we use several services that listen to and handle those events. One of the key services transforms those events into Webhooks and sends them to the configured URLs.

Some of the fields that we expose in the Webhooks are related to those events, and we share them so that we can always refer back to the events that triggered them. This is extremely useful when you want to know more about the context of the event or the data that is being sent.

These fields include:

  • mesageType: The type of event that triggered the webhook.
  • messageId: The unique identifier of the event that triggered the webhook.

Now, this is important when you subscribe to the webhooks that we expose because the messageType describes the fact that happened within the platform. For example, event.claim.created is emitted when a Claim was created within the platform, and event.claim.updated is emitted when the Claim was updated. You can subscribe independently to those Webhooks, which will give you immediate feedback about the changes occurring in the platform.

Next, messageId is useful because it serves as the unique identifier of the event that triggered the Webhook. This allows you to refer back to the event that triggered the webhook. Also, because there is a retry mechanism if the Webhook failed to process, you can use messageId to ensure you do not process the same event twice.

Example of a Webhook​

{
  "payload": {
    "details": {
      "messageType": "event.claim.created.v1",
      "accountReference": "PDN-922-Oct14-0001",
      "claimRef": "PDN-922-claim-Oct14-00010",
      "receeveClaimRef": "PDN-922-claim-Oct14-00010",
      "amount": 501,
      "currency": "EUR",
      "dueDate": "2021-10-07"
    },
    "messageId": "09feeb6f-350a-430a-a040-cd1c558cbc91",
    "timestamp": "2021-10-14T15:33:16.848Z",
    "user": {
      "id": "USER_ID",
      "poolId": "POOL_ID",
      "originator": "ClientAPI"
    }
  },
  "signature": "SIGNATURE",
  "payloadAsString": "PAYLOAD_AS_STRING"
}

Notes:

  • The details field contains information about the event. (Required)
  • The messageId field contains the unique webhook’s identifier. It is useful to avoid processing the same webhook twice, and this is the same identifier of the event within the platform. Therefore, it can be used to track the event in the platform. (Required)
  • The timestamp field contains the event’s timestamp of when it was sent to the Message Bus. (Required)
  • The user field contains information about the user that triggered the event. (Optional)
  • The signature and payloadAsString fields are used to validate the webhooks. Please refer to the Webhook Validation Use Case section for more details.

Users​

There are 3 user sources that can trigger events in the platform:

  • The Client API
  • The Debtor on the Landing Page
  • The Backoffice Agents/Supervisors/Admins, etc.

We include the user field in the Webhooks so you can know who triggered the event that triggered the Webhook.

Note: The user context is optional because in some use cases the system doesn’t have such context. This is true for events triggered as part of the process of the system, such as part of the collection Strategy, as a side effect of a reaction, etc.

Webhook Good Practices​

  • Please validate the Webhook’s signature before processing it in the system.
  • It is highly recommended that users process the webhooks asynchronously using a Message Bus or a Queue. This will ensure that your system is not blocked if the processing of a webhook takes a long time. This also ensures it can handle the backpressure if there is a large number of webhooks.

FAQ

  • How do I trigger a Webhook? Webhooks require two ingredients to be triggered:
    • First, the subscription to the target event must be configured using the Backoffice.
    • Second, the event related with that subscription must be emitted. The event is emitted to represent a fact that was recognized in the platform. For example, the event.claim.created is emitted when a Claim is created, and the event.claim.updated is emitted when a Claim is updated. Notice that the Webhooks are not triggered by the API; instead, they are triggered by the events that are emitted by the platform. Those events are triggered as side-effects of the actions performed in the platform, and some (but not all) of those actions can be triggered by the API. For example:
    • The event.claim.created is emitted when a Claim is created, which can be triggered by the API through different API endpoints.
    • The event.claim.updated is emitted when a Claim is updated, which can be initiated by the API, but also by the system such as when the Claim is updated as part of the Collection Strategy.
  • I can’t find the Webhook related to the event that I need. What do I do? Please contact us for help with this. We expose only the most relevant events for our clients through Webhooks, but we can expose more events if needed.

Related Pages