Webhooks

Webhooks let DT One push event notifications to your systems as they happen, so you do not have to poll for changes. When a supported event occurs, DT One sends an HTTP POST request to a URL you have registered, carrying a JSON payload that describes the event.

📘

Webhooks are not transaction callbacks

Webhooks are separate from the DVS transaction callback (callback_url) you set when creating a transaction. The transaction callback delivers the full transaction object as it moves through its lifecycle (for example, to COMPLETED). Webhooks deliver discrete downstream events about a provisioned service — for example, an eSIM being installed or a data balance running low — which have no matching transaction status change. You can use both independently.

Configuring a webhook

Webhooks are managed in DT Shop → Developers → Webhooks, per environment (Production and Pre-production have independent configurations).

To add one:

1. Choose a Webhook Type from the dropdown (see Webhook event reference for the types available today).
2. Enter the Webhook URL that should receive events of that type.
3. Click Add Webhook.

Notes:

• One URL per type. Each webhook type is delivered to a single configured URL. Register a separate endpoint for each type you want to receive.
• URL requirements. The URL must be a valid http or https address with a host. HTTPS is strongly recommended — the payload is unauthenticated (see Security below), and HTTPS is required for the upstream provider integrations.
• Configurations are independent per environment; set up your pre-production endpoint first to test, then add the production one.

The request DT One sends

Every webhook, regardless of type, is delivered the same way.

Method and headers

Events are delivered as an HTTP POST with the following headers:

Body (envelope)

The body is a JSON envelope that is the same shape for every webhook type. The type-specific fields live inside the data object:

{
  "id": "1288",
  "created_at": "2026-07-26T10:15:30Z",
  "data": {
    // type-specific fields — see the Webhook event reference
  }
}

📘

Read the type from the header, the details from data

The envelope (id, created_at, data) never changes as new event types are added. Route on the X-Webhook-Type header, then parse the fields inside data for that type. Treat data as an open object: ignore fields you do not recognize so your integration keeps working when fields are added.

Responding to a webhook

Your endpoint should return an HTTP 2xx status to acknowledge receipt. Return a non-2xx status only if you were genuinely unable to accept the event.

🚧

Delivery is best-effort and single-attempt

DT One sends each event once. There is currently no automatic retry and no backoff: if your endpoint returns a non-2xx status, times out, or is unreachable, that delivery is not retried. The request also times out after 5 seconds, so your endpoint must acknowledge quickly — do the minimum needed to accept the payload (persist it and return 2xx), and process it asynchronously.

Because delivery is at-least-once at the transport layer, your endpoint may occasionally receive the same event more than once. Use the envelope id to make processing idempotent.

Security

The webhook request is not signed or authenticated — there is currently no HMAC signature, bearer token, or shared-secret header on the request. To protect your endpoint:

• Serve your endpoint over HTTPS and keep the URL secret.
• Treat the payload as untrusted input: validate its shape, and where an event carries an identifier you can cross-check (for example, a transaction_id), verify it against your own records before acting on it.
• Consider hosting the endpoint at an unguessable path.

Available event types

See the Webhook event reference for the full list of supported webhook types and the exact data schema of each. Today all supported events relate to eSIM services; the envelope, headers, and delivery behaviour described above apply to any event types added in the future.