Webhooks

Note: This is a “preview” feature and may be subject to change.

Introduction

Webhooks allow API users to receive timely updates without constant polling. You can register a URL to receive a POST request whenever there are changes in the data exposed by the API.

Message structure

Each message has a generic envelope that wraps the data of the event. The data uses the same schema as the API’s endpoints. Here’s an example of a customer update message:

{
  "id": "5615894c-56ba-73ac-8fc8-4120262d7fd9",
  "occurred_at": "2022-11-01T01:02:45.123Z",
  "modification_kind": "update",
  "kind": "customer",
  "data": {
    "id": "ca904ea7-4281-714e-a3cd-72df1d61907b",
    "admin_id": "tdr-france",
    "name": "TandemDrive BV",
    "country": "NL",
    "entity_type": "organisation",
    "company_reg_num": "C123456",
    "external_reference": "ABC-123",
    "created_at": "2022-11-01T01:01:45.123Z",
    "updated_at": "2022-11-01T01:02:45.123Z",
    "billing_email": "info@tandemdrive.com",
    "billing_phone": "+31123456789",
...
  }
}

Object deletions, contain properties to identify the object that was deleted in data. See Deletions below.

For the details about the structure of the envelope see the API specification.

Webhook registration

When subscribing to a webhook, you can specify which event kinds to receive. If different endpoints need updates for different kinds, multiple webhook subscriptions can be registered. While messages for each subscription are guaranteed to be sequential, there is no guarantee of the order between different subscriptions.

Messages may be sent concurrently to different webhook subscribers. However, for each individual subscriber, only one message is sent at a time to ensure that events are processed in the exact order they occurred.

Responses

The HTTP response code confirms the receipt of the update. Non-2xx responses will trigger retries by TandemDrive.

As a webhook receiver, you should reject messages only in rare cases like authentication failures or system errors. In all other situations, respond with a 2xx status code to avoid disrupting the delivery of subsequent messages due to a single rejection.

Webhook endpoints must support at least HTTP 1.1 and TLS 1.3. Accepting compressed HTTP requests is recommended for efficiency.

Authentication

To ensure security, you must verify that events originate from TandemDrive. This can be done using configurable headers like X-Api-Key or Authorization. The receiving URL should use https:// with a valid certificate.

Rapid Events

For rapid successive updates it may be possible that we either de-duplicate events of the same object as a single event, or send one event per update but each with the same state of the object.

Deletions

In deletion events, only the object identifier and external reference (if available) are included:

{
  "id": "5615894c-56ba-43ac-8fc8-4120262d7fd9",
  "occurred_at": "2022-11-01T01:02:45.123Z",
  "modification_kind": "delete",
  "kind": "customer",
  "data": {
    "id": "ca904ea7-4281-414e-a3cd-72df1d61907b",
    "external_reference": "C0001234"
  }
}

However this rule has some notable exceptions, for objects where there exists a domain identifier that is used instead of the id generated by TandemDrive. The list of object to which this exception applies:

Performance

Prepare to handle potentially high volumes of messages. TandemDrive sends data in batches (e.g., every 10 seconds) via a single TCP+TLS connection. Be sure to quickly deliver a 2xx response to avoid timeouts.

Handling duplicate events

Our webhook system will retry delivery until your endpoint returns a successful response. If we don’t fully process your response, the same message may be sent more than once. To handle potential duplicates, ensure your event processing is idempotent by tracking the ids of received events and skipping those already processed.