Skip to main content

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:read or webhooks:*
  • 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.

FieldTypeNotes
id—
subscriptionId—
eventId—
eventName—
status—
attempts—
maxAttempts—
nextAttemptAtstring
lastStatus—
lastError—
queuedAtstring
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:write or webhooks:*
  • 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:read or webhooks:*
  • 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.

FieldTypeNotes
itemsarray 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:read or webhooks:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
Query parameterTypeNotes
limitstring
cursorstring

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray 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:write or webhooks:*
  • 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.

FieldTypeNotes
deliveryIdsarray of string (UUID)

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray 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": []}'