Skip to main content

Webhooks

Summary​

This section primarily documents Event Webhooks. Some webhook configuration, such as additional HTTP headers, also applies to Message and Transaction webhooks.

Our system uses a push-based event notification system that proactively sends events related to the user journey via webhooks. It first creates a persistent batch record containing specific events based on time/count thresholds. A separate process then attempts to deliver this exact batch via webhook to your configured endpoint, retrying automatically upon transient failures. Partners must handle webhook deliveries idempotently using the provided batch_id.

Reliable Delivery & Retries​

If a webhook delivery attempt fails (i.e., does not receive an HTTP 2xx success response), the system will automatically retry sending the batch. Retries use a polynomial backoff strategy, attempting delivery for approximately 30 days (up to 26 attempts) before marking the batch as failed.

Depo Configurations​

You can register the endpoint where Event Webhooks should be delivered in Depo. You can also configure your batching preferences (time/count thresholds), subscribe to specific event types, and configure additional HTTP headers.

Up to 5 additional HTTP headers can be configured per partner. These headers are sent with Event, Message, and Transaction webhooks.

Header names must be valid HTTP header names and unique per partner. Headers managed by the application, including Host, Content-Length, Content-Type, and Accept, cannot be overridden.

Time/Count Batching​

We allow our partners to specify the event types they want to receive. These can be batched in a hybrid approach, based on time or on a count of a number of events.

Time-wise we support configurable time windows (default: 1 second up to 1 minute), while batch sizes may range up to a configurable maximum (default: 100 events). Events are batched when either the time window expires since the last batch creation or the maximum batch size is reached.

Payload Format​

Our event webhooks are delivered via HTTP POST requests with the following characteristics:

  • Content-Type Header: The Content-Type header is always application/json.
  • Payload Format: The body of the request is a JSON object.
  • Sample Payload: Below is an example of the JSON payload structure you will receive:
{
  "batch_id": "uuid",
  "timestamp": "2024-03-21T10:00:00Z",
  "count": 3,
  "events": [
    {
      "id": "uuid",
      "createdAt": "2024-03-21T10:00:00Z",
      "type": "string" /* event type */,
      "data": { ... } /* event object */
    },
    ...
  ]
}

See the Event Webhooks page for details on the structure of the individual event objects (like the one shown above) within the events array.

Partners must handle webhook deliveries idempotently using the provided batch_id.

Reliability and Idempotency​

Webhook delivery is handled by a separate background process after a batch is created. If a webhook delivery attempt fails (i.e., does not receive an HTTP 2xx success response), the system will automatically retry sending the exact same batch.

Retries use a polynomial backoff strategy, attempting delivery for approximately 30 days (up to 26 attempts). If delivery is still unsuccessful after this period, the batch is marked as failed and no further attempts are made. This retry duration balances ensuring delivery with managing system resources and preventing indefinite retries for permanently unavailable endpoints.

Critical: Because the same batch might be delivered multiple times during retries, your endpoint must handle incoming webhooks idempotently. Use the batch_id provided in the payload to identify and deduplicate batches you have already processed.

mTLS authentication​

mTLS (Mutual TLS) authentication is a security mechanism where both the client and the server authenticate each other using TLS certificates. Both the client and server must have valid TLS certificates issued by a trusted Certificate Authority (CA).

We authenticate webhook calls using our pre-existing mTLS infrastructure. Payloads are transmitted securely over HTTPS. Additional HTTP headers can be used alongside mTLS.