Skip to content

Webhooks

Webhooks notify your server when relevant ZTL resources change. They help keep your system and customer-facing statuses up to date without waiting for the next poll. This includes changes that occur after a resource was previously considered final.

The available event families are PAYMENT_STATUS, PAYROLL_STATUS, and ONBOARDING_STATUS. Webhooks complement your normal reconciliation process; retain resource IDs and use the relevant status API when you need to reconcile an unknown or missed outcome.

  1. Create a subscription with a public HTTPS endpoint and the event types you want to receive.
  2. Store the returned signing secret in your receiving service. It is shown only when the subscription is created or when you rotate it.
  3. Optionally configure a bearer token if your endpoint requires it.
  4. Call the test-delivery endpoint and confirm that your endpoint accepts the request.

Use the webhook API reference to create, list, update, and disable subscriptions. Subscriptions are available only to the authenticated partner that created them. Status events are delivered only to subscriptions belonging to the partner that owns the payment, payroll, or onboarding.

Your endpoint must use HTTPS and be reachable from the public internet. Do not use a browser-return URL as a webhook endpoint; browser returns and webhooks serve different purposes. See callbacks for browser returns.

Authenticate subscription-management requests with your normal ZTL API access token in Authorization: Bearer {accessToken}. This is separate from the optional bearer token that ZTL sends to your receiving endpoint.

For example, send this JSON body to POST /api/webhooks/subscription:

{
"targetUrl": "https://partner.example/webhooks/ztl",
"eventTypes": ["PAYMENT_STATUS", "PAYROLL_STATUS", "ONBOARDING_STATUS"]
}

The response is HTTP 201 and includes the subscription id and signingSecret. New subscriptions are enabled immediately. Creating a subscription does not replay earlier events.

You can create multiple subscriptions, each with its own endpoint, event types, and credentials. To update one, send both targetUrl and the complete desired eventTypes list to PATCH /api/webhooks/subscription/{id}. At least one event type is required. Listing subscriptions includes both enabled and disabled ones. If a subscription contains an event type that this API version no longer recognizes, list and get responses still return its stored name. That type does not match events published by this version. Updating the subscription replaces the complete event type list, and the update request must use supported types.

Subscribe to a parent type to receive every public status change in that event family. Subscribe to one or more child types when you only need selected statuses. Event type names are case-sensitive.

Subscription type Receives transitions to
PAYMENT_STATUS Any of the statuses below.
PAYMENT_STATUS_UNSIGNED Unsigned
PAYMENT_STATUS_IN_PROGRESS InProgress
PAYMENT_STATUS_REJECTED Rejected
PAYMENT_STATUS_COMPLETED Completed
PAYMENT_STATUS_CANCELLED Cancelled
PAYMENT_STATUS_CUSTOMER_ACTION_REQUIRED CustomerActionRequired
Subscription type Receives transitions to
PAYROLL_STATUS Any of the statuses below.
PAYROLL_STATUS_UNSIGNED Unsigned
PAYROLL_STATUS_IN_PROGRESS InProgress
PAYROLL_STATUS_REJECTED Rejected
PAYROLL_STATUS_COMPLETED Completed
PAYROLL_STATUS_CANCELLED Cancelled
PAYROLL_STATUS_CUSTOMER_ACTION_REQUIRED CustomerActionRequired
Subscription type Receives transitions to
ONBOARDING_STATUS Any of the statuses below.
ONBOARDING_STATUS_CREATED Created
ONBOARDING_STATUS_AWAITING_CUSTOMER_ACTION AwaitingCustomerAction
ONBOARDING_STATUS_PROCESSING Processing
ONBOARDING_STATUS_MANUAL_HANDLING ManualHandling
ONBOARDING_STATUS_ACCEPTED Accepted
ONBOARDING_STATUS_REJECTED Rejected

Deliveries always identify the specific child type that occurred, including when you subscribed through the parent type. For example, a subscription to PAYMENT_STATUS receives an event with type PAYMENT_STATUS_COMPLETED when a payment completes. Likewise, ONBOARDING_STATUS receives ONBOARDING_STATUS_ACCEPTED when an onboarding is accepted. PAYROLL_STATUS receives PAYROLL_STATUS_COMPLETED when a recipient’s payroll transaction completes.

Selecting both the parent and a matching child does not create two deliveries for the same subscription. Separate matching subscriptions each receive a delivery.

ZTL sends an HTTP POST request with a JSON body. A successful response is any 2xx response. Verify and persist the event before returning a successful response, then process it asynchronously if your workflow needs more time.

Respond within 10 seconds. Your endpoint must present a valid, publicly trusted TLS certificate for its hostname; self-signed certificates are not supported. Creating a subscription validates the URL format, but does not verify endpoint reachability. Use the test endpoint to check delivery.

Header Purpose
X-ZTL-Webhook-Id Identifies this delivery. Include it in support logs.
X-ZTL-Webhook-Event The specific event type, such as PAYMENT_STATUS_COMPLETED.
X-ZTL-Webhook-Timestamp Unix timestamp in seconds used for signature verification.
X-ZTL-Webhook-Signature Signature in the form v1={hex-hmac}.
Authorization Present only when you configured a bearer token. Its value is Bearer {token}.

The signing secret is always used to sign deliveries. Verify the signature before parsing or acting on the body:

  1. Read the raw request body and the timestamp header.
  2. Reject timestamps outside the acceptance window your service defines.
  3. Compute an HMAC-SHA256 using the UTF-8 bytes of the signing secret as returned by the API (do not Base64-decode it) over {timestamp}.{raw request body}.
  4. Compare the resulting hex value with the value after the v1= prefix using a constant-time comparison.

Never expose, log, or send the signing secret to a browser. Treat a bearer token as an additional endpoint-authentication control, not as a replacement for signature verification.

ZTL may retry a delivery that does not receive a successful response. Your handler must therefore tolerate duplicate deliveries and events that arrive out of order.

  • Use the event body’s id as your idempotency key.
  • Persist the received event before triggering any side effect in your system.
  • Accept future event types and status values without failing deserialization.
  • Use occurredAt to detect older events and avoid overwriting a newer status with a delayed delivery. Reconcile ambiguous ordering through the relevant status API. Do not assume that a previous final status cannot later change.
  • Do not display optional statusReasonText directly to an end user. It is intended for operational context and support.

ZTL retries network failures and HTTP 408, 429, and 5xx responses, with up to six delivery attempts per delivery cycle. Retry delays are approximately 1, 5, 30, 120, and 360 minutes after successive failures. Other unsuccessful HTTP responses are not retried. Redirects are not followed, and destinations that resolve to non-public addresses are rejected without retry.

After retries are exhausted, the delivery becomes FAILED and automatic delivery stops. You can inspect its history and request a manual retry after fixing your endpoint. Reconcile any missed updates through the relevant status API.

Investigate endpoint availability, TLS configuration, authentication, and signature verification before requesting support. Include the delivery ID and event ID in your support request, but never include secrets or bearer tokens.

Use list webhook deliveries at GET /api/webhooks/subscription/{id}/deliveries to inspect deliveries for a subscription. Authenticate with your normal ZTL API access token. History is available for both your enabled and disabled subscriptions.

Only deliveries created within the last 30 days are accessible. Creating a new subscription does not recover earlier events.

Query parameter Behavior
status Optional, case-sensitive filter: PENDING, IN_PROGRESS, DELIVERED, or FAILED.
from Inclusive delivery creation time, in ISO 8601 format with a timezone. Defaults to 30 days ago; earlier values are limited to that window.
to Exclusive delivery creation time, in ISO 8601 format with a timezone. Defaults to now. from must be before to.
limit Page size from 1 to 100; defaults to 50.
cursor Opaque continuation value returned as nextCursor by the previous page.

Results are ordered newest first by creation time, then delivery ID. The response contains deliveries and, when another page exists, nextCursor. Keep your filters unchanged when requesting the next page; use fixed from and to values if you need a consistent time window. Stop when nextCursor is absent or null. Invalid filters or a malformed cursor return HTTP 400.

For example, list failed deliveries with GET /api/webhooks/subscription/{id}/deliveries?status=FAILED&limit=50:

{
"deliveries": [
{
"id": "7e849bde-ae54-4d12-920b-c079929646ba",
"eventType": "PAYMENT_STATUS_COMPLETED",
"status": "FAILED",
"createdAt": "2026-10-06T10:00:00Z",
"attemptCount": 1,
"lastAttemptAt": "2026-10-06T10:00:01Z",
"lastResponseCode": 401,
"lastError": "Webhook endpoint returned HTTP 401"
}
]
}
Delivery status Meaning
PENDING Queued for its first attempt, an automatic retry, or a manual retry.
IN_PROGRESS An attempt has been claimed for delivery.
DELIVERED Your endpoint returned a successful 2xx response. Eligible for manual replay if the subscription is enabled.
FAILED Automatic delivery stopped after a non-retryable failure or exhausted attempts. Eligible for manual retry if the subscription is enabled.

Each summary includes a cumulative attemptCount across the initial cycle and all manual retry cycles. Optional fields include lastAttemptAt, deliveredAt, nextAttemptAt, lastResponseCode, and lastError. nextAttemptAt is provided only for PENDING deliveries. After a manual retry is accepted, the last response and error still describe the previous attempt until another attempt finishes.

Use get webhook delivery at GET /api/webhooks/subscription/{id}/deliveries/{deliveryId} for details:

  • delivery: the same delivery summary returned by the list endpoint.
  • payload: the original event as a JSON object, including its event ID.
  • attempts: recorded attempts in attempt-number order, with start and completion times, the target URL used, and any HTTP response code or safe error message. An unfinished attempt can have no completion time or result.
  • retries: accepted manual retry requests, with an ID and requestedAt time, ordered oldest first.

Signing secrets and bearer tokens are never returned by history endpoints. Missing subscriptions, another partner’s subscriptions, mismatched delivery IDs, and deliveries outside the 30-day window return HTTP 404.

You can replay failed deliveries or deliveries your endpoint already acknowledged with a successful response, for example to recover from a downstream processing problem. For failed deliveries, fix the endpoint, authentication, or other delivery problem first. Call retry webhook delivery with POST /api/webhooks/subscription/{id}/deliveries/{deliveryId}/retry. No request body is required.

Only a FAILED or DELIVERED delivery created within the last 30 days can be replayed, and its subscription must be enabled. The request schedules the same delivery for asynchronous processing and returns HTTP 202:

{
"deliveryId": "7e849bde-ae54-4d12-920b-c079929646ba"
}

Requests for PENDING or IN_PROGRESS deliveries return HTTP 409.

Acceptance does not mean your endpoint received the event. Check delivery history for the result. A manual retry starts a new cycle with up to six attempts under the normal retry policy. Previous attempts and retry requests remain in history, and attemptCount continues increasing.

Acceptance changes the delivery status to PENDING and clears deliveredAt, including when replaying a previously delivered webhook. Earlier successful attempts remain in attempts. A new successful delivery sets deliveredAt to the new completion time; the replay can also end in FAILED.

Replay preserves the delivery ID, event ID, and original event body, including occurredAt for status events. Each attempt uses a fresh signature timestamp. Keep deduplicating on the event body’s id, and avoid replacing a newer resource status with an older replayed event.

Replaying a delivered webhook does not bypass your receiver’s deduplication. If you need to repeat downstream processing, handle that recovery explicitly in your system while continuing to guard against duplicate side effects.

Unlike automatic retries, a manual retry snapshots the subscription’s current target URL, signing secret, and bearer token when the retry is accepted. Later subscription edits do not change that queued retry cycle. Event-type changes do not prevent replaying a previously queued delivery.

Response Meaning
202 Retry accepted and queued. The body contains the existing deliveryId.
404 Subscription or delivery is unavailable to your partner, or the delivery is outside the 30-day window.
409 The subscription is disabled or the delivery is neither FAILED nor DELIVERED, including when a retry is already queued or in progress.
429 The subscription has reached the limit of 10 accepted manual retry requests per minute. Wait according to Retry-After: 60 before retrying.

There is no bulk replay or replay of events that were never queued for the subscription. For deliveries outside the history window, use the relevant resource status API to reconcile your system.

A PAYMENT_STATUS_* event is emitted when a payment is created or its public status changes. The initial event has previousStatus: null. Subscribe before creating the payment to receive it. The event type is always the specific status child type. paymentId identifies the payment in the Payments API. previousStatus and status use the public payment status values shown above, including their casing. A change to a status reason alone does not produce an event.

statusReason is an optional code such as PartlySigned, SmsConfirmationRequired, or InsufficientFunds. statusReasonText provides optional additional context. Handle absent or null reason fields, and allow for new status and reason values over time.

{
"id": "43ccf9e9-5026-4fb5-9614-a9cd44298912",
"type": "PAYMENT_STATUS_CUSTOMER_ACTION_REQUIRED",
"version": "1",
"occurredAt": "2026-09-02T10:00:00Z",
"data": {
"paymentId": "6b0ce7dc-19ed-4e0c-87a2-3df0eeecfb4d",
"previousStatus": "InProgress",
"status": "CustomerActionRequired",
"statusReason": "SmsConfirmationRequired",
"statusReasonText": null
}
}

The event ID identifies the status-change event. The delivery ID is separate and identifies delivery to a particular subscription. Retries reuse the delivery ID and event body, with a fresh timestamp and signature for each attempt.

A PAYROLL_STATUS_* event is emitted when a payroll recipient transaction is created or its public status changes. The event type is always the specific status child type. previousStatus and status use the public payroll status values shown above, including their casing.

Identify the recipient transaction using both payrollId and endToEndId. endToEndId is the value supplied in that transaction’s metadata.endToEndId when creating the payroll and returned by the payroll status API. An event for one recipient does not determine the outcome for the other recipients.

Subscribe before creating the payroll to receive each transaction’s initial event. Its previousStatus is null, and its type reflects the initial public status, for example PAYROLL_STATUS_UNSIGNED for Unsigned.

{
"id": "ed90a3ac-64bc-43a4-a85a-871cd746094e",
"type": "PAYROLL_STATUS_COMPLETED",
"version": "1",
"occurredAt": "2026-10-26T10:00:00Z",
"data": {
"payrollId": "6b0ce7dc-19ed-4e0c-87a2-3df0eeecfb4d",
"endToEndId": "salary-2026-10-001",
"previousStatus": "InProgress",
"status": "Completed"
}
}

Internal changes that leave the public status unchanged do not produce an event. For example, funding completion and payout initiation can both remain InProgress. A change to a status reason alone does not produce an event.

Use GET /api/v2/payroll/{payrollId}/status to reconcile missed deliveries or fetch all recipient statuses and any payrollStatusReason. Payroll webhook payloads do not include status reasons. Track event ordering separately for each payrollId and endToEndId pair. See the payroll guide for funding, approval, and cancellation handling.

An ONBOARDING_STATUS_* event is emitted when an onboarding is created or its public status changes. The event type is always the specific status child type. onboardingId identifies the onboarding in the Onboarding API. previousStatus and status use the public onboarding status values shown above. For the initial Created event, previousStatus is null. Changes that leave the public status unchanged do not produce an event. Events are delivered only to subscriptions belonging to the onboarding’s partner.

{
"id": "43ccf9e9-5026-4fb5-9614-a9cd44298912",
"type": "ONBOARDING_STATUS_ACCEPTED",
"version": "1",
"occurredAt": "2026-09-02T10:00:00Z",
"data": {
"onboardingId": "6b0ce7dc-19ed-4e0c-87a2-3df0eeecfb4d",
"previousStatus": "Processing",
"status": "Accepted"
}
}

Use GET /onboarding/{onboardingId}/status to fetch the current status and signer details after an event or to reconcile a missed delivery. The webhook contains the public status transition, not the signer-level details.

Call POST /api/webhooks/subscription/{id}/test for an enabled subscription. It sends a webhook.test event regardless of the subscription’s selected event types. The test payload contains id, type, and createdAt; it does not have the status events’ data object.

The API returns HTTP 200 with deliveryId, succeeded, and an optional error. Check succeeded: HTTP 200 alone does not mean your endpoint received the webhook successfully. On failure, error describes the delivery problem. Retryable test failures follow the same retry policy as other deliveries. An unknown, disabled, or other partner’s subscription returns HTTP 404.

Test requests have an allowance of 10 per partner per application instance, shared across all subscriptions and refilled every 60 seconds. Requests that return a delivery failure or subscription error also consume the allowance. Once exhausted, further requests return HTTP 429 with a Retry-After header indicating how many seconds to wait, without creating a delivery.

Rotate the signing secret with the signing-secret endpoint, and set or rotate a bearer token with the bearer-token endpoint. Update the receiving service at the same time as a rotation so it continues to accept deliveries. The API never returns a configured bearer token; it returns only whether one is configured. Send only the token value in bearerToken, without the Bearer prefix. Tokens must not be blank. Updating a subscription does not change its bearer token; use POST /api/webhooks/subscription/{id}/rotate-bearer-token for that. Already queued deliveries retain the endpoint and credentials in effect when they were queued. An accepted manual retry uses the current subscription endpoint and credentials as described in replay a delivery. Allow an overlap period for old and new credentials while those deliveries finish. Disabling a subscription stops new events from being queued but does not cancel existing deliveries.

There is currently no endpoint to re-enable a disabled subscription or remove a configured bearer token. Create a replacement subscription if needed, and disable the old one when the replacement is ready.

Use the test-delivery endpoint after changing your endpoint, signing secret, or bearer token.