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.
Set up a subscription
Section titled “Set up a subscription”- Create a subscription with a public HTTPS endpoint and the event types you want to receive.
- Store the returned signing secret in your receiving service. It is shown only when the subscription is created or when you rotate it.
- Optionally configure a bearer token if your endpoint requires it.
- 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.
Choose event types
Section titled “Choose event 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.
Payment statuses
Section titled “Payment statuses”| 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 |
Payroll transaction statuses
Section titled “Payroll transaction statuses”| 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 |
Onboarding statuses
Section titled “Onboarding statuses”| 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.
Receive and verify deliveries
Section titled “Receive and verify deliveries”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:
- Read the raw request body and the timestamp header.
- Reject timestamps outside the acceptance window your service defines.
- 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}. - 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.
Process events safely
Section titled “Process events safely”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
idas 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
occurredAtto 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
statusReasonTextdirectly 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.
Inspect delivery history
Section titled “Inspect delivery history”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 andrequestedAttime, 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.
Replay a delivery
Section titled “Replay a delivery”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.
Payment status events
Section titled “Payment status events”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.
Payroll status events
Section titled “Payroll status events”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.
Onboarding status events
Section titled “Onboarding status events”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.
Test an endpoint
Section titled “Test an endpoint”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 credentials
Section titled “Rotate credentials”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.