Receiving Calls

Once you have created a webhook configuration, Taurus-PROTECT will monitor for events that match the webhook’s type. When the event is observed, a webhook call model is created and stored in the database. This model is then used to perform the HTTP POST calls in order of creation to the specified webhook URL. A call will contain the following:

Headers:

• x-webhook-id: This is the unique ID of the call, which should be observed so that the same call is not consumed twice. If a call appears to have failed, it will be retried with the same ID.
• x-webhook-timestamp: Unix timestamp of the call attempt. If the call is retried, the this value will be updated. This is not the same as the event’s timestamp found in the payload.
• x-webhook-signature: A space delimited list of signatures that verify authenticity of the call. See the section on webhook call signatures for details about the signed data.

Payload:

• type: Specifies the type of payload being sent.
• createdAt: Indicates when the webhook event was first observed. This will not change if a call is retried.
• data: Information about the event that took place. This varies by event type. For further details, see the chapter on webhook types.

Example of a webhook call:

# POST client.url
# Headers:
  x-webhook-id:        0009728d-e612-4434-93bf-48e47b2f0fd3,
  x-webhook-timestamp: 1715616466,
  x-webhook-signature: "v1,qGQSdv0kdiN6WFreSaaZmR3Sb5P+neHo/OpAWYcZ3RU="
# Payload:
{
  "type": "currencyStatus.updated",
  "createdAt": "2024-05-13T16:07:43.79968Z",
  "data": {
    "currencyId": "abc123",
    "currency": "Bitcoin",
    "status": "enabled"
  }
}

Failing to receive a call

A webhook call is considered successful if the client application responds to the call with an HTTP code in the 200-299 range. Any other response counts as a failure. Consecutive failure responses increment a counter on the webhook while a successful response sets the counter back to 0. The webhook will enter a cooldown period each time the counter increments. The duration of this period is a simple exponential pattern shown below:

# Number of consecutive failures: Time until next possible call
1:  None
2:  4 minutes
3:  8 minutes
4:  16 minutes
5:  32 minutes

A single failure causes no timeout, and any number exceeding 5 leads to a 32 minute timeout. Calls will continue once the timeout passes, starting with the oldest. Calls older than 24 hours will no longer be tried.