Webhooks: deliveries, events, dead letters
5 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.
How deliveries are signed and retried is in Webhooks.
Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.
A delivery with its attempts
GET /v1/webhooks/{id}/deliveries/{deliveryId}
- Scope:
webhooks:readorwebhooks:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
Path parameters: id, deliveryId.
Request
No body.
Response
200: fields the handler writes, taken from its source. The service's OpenAPI document describes a different body; this page follows the handler.
| Field | Type | Notes |
|---|---|---|
id | — | |
subscriptionId | — | |
eventId | — | |
eventName | — | |
status | — | |
attempts | — | |
maxAttempts | — | |
nextAttemptAt | string | |
lastStatus | — | |
lastError | — | |
queuedAt | string | |
deliveredAt | — | |
test | — |
Example
curl "https://api.zaitrack.app/v1/webhooks/$ID/deliveries/$DELIVERY_ID" \
-H "Authorization: Bearer zk_test_…"
Replay a delivery
POST /v1/webhooks/{id}/deliveries/{deliveryId}:replay
- Scope:
webhooks:writeorwebhooks:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: no
- Step-up MFA: no
Path parameters: id, deliveryId.
Request
No body: the handler reads none.
Response
200: fields the handler writes, taken from its source. The service's OpenAPI document describes a different body; this page follows the handler.
The same fields as the response of A delivery with its attempts.
Example
curl -X POST "https://api.zaitrack.app/v1/webhooks/$ID/deliveries/$DELIVERY_ID:replay" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)"
Event types a subscription can receive
GET /v1/webhooks/events
- Scope:
webhooks:readorwebhooks:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].name | — | |
items[].description | — | |
items[].version | — | |
items[].schema | — | |
items[].sample | — |
Example
curl "https://api.zaitrack.app/v1/webhooks/events" \
-H "Authorization: Bearer zk_test_…"
Dead-lettered deliveries across every subscription
GET /v1/webhooks/dead-letters
- Scope:
webhooks:readorwebhooks:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
| Query parameter | Type | Notes |
|---|---|---|
limit | string | |
cursor | string |
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].id | — | |
items[].subscriptionId | — | |
items[].eventId | — | |
items[].eventName | — | |
items[].status | — | |
items[].attempts | — | |
items[].maxAttempts | — | |
items[].nextAttemptAt | — | |
items[].lastStatus | — | |
items[].lastError | — | |
items[].queuedAt | — | |
items[].deliveredAt | — | |
items[].test | — |
Example
curl "https://api.zaitrack.app/v1/webhooks/dead-letters" \
-H "Authorization: Bearer zk_test_…"
Re-send dead-lettered deliveries (up to 100)
POST /v1/webhooks/dead-letters:replay
- Scope:
webhooks:writeorwebhooks:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: low risk
- Step-up MFA: no
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
deliveryIds | array of string (UUID) |
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].deliveryId | — |
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/webhooks/dead-letters:replay" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"deliveryIds": []}'