Skip to main content

Webhooks: basics, secrets, deliveries

8 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.

List webhook subscriptions​

GET /v1/webhooks

  • 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[].id—
items[].url—
items[].description—
items[].events—
items[].filters—
items[].retryPolicyobject
items[].retryPolicy.maxAttemptsinteger
items[].retryPolicy.timeoutSinteger
items[].retryPolicy.backoffstring
items[].status—
items[].disabledReason—
items[].consecutiveFailures—
items[].createdBy—
items[].createdAtstring
items[].updatedAtstring
items[].version—
items[].previousSecretExpiresAt—
items[].secret—

Example​

curl "https://api.zaitrack.app/v1/webhooks" \
-H "Authorization: Bearer zk_test_…"

Subscribe a URL to events (secret shown once)​

POST /v1/webhooks

Leave secret out and the service generates one (whsec_…); a secret you choose has 24 to 128 characters. The response carries it once. Keep it: deliveries are signed with it (see Verify a delivery).

  • Scope: webhooks:write or webhooks:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: medium risk
  • Step-up MFA: no

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
urlstring
descriptionstring
eventsarray of string
filtersobject
filters.severityAtLeaststringoptional
filters.vehicleIdsarray of string (UUID)optional
filters.divisionIdsarray of string (UUID)optional
filters.predicateany JSONoptional
secretstring
retryPolicyobject
retryPolicy.maxAttemptsinteger
retryPolicy.timeoutSinteger
retryPolicy.backoffstring

Response​

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

FieldTypeNotes
id—
url—
description—
events—
filtersobject
filters.severityAtLeast—
filters.vehicleIdsarray
filters.divisionIdsarray
retryPolicyobject
retryPolicy.maxAttemptsinteger
retryPolicy.timeoutSinteger
retryPolicy.backoffstring
status—
disabledReason—
consecutiveFailures—
createdBy—
createdAtstring
updatedAtstring
version—
previousSecretExpiresAt—
secret—

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/webhooks" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"url": "…", "description": "…", "events": [], "filters": {"severityAtLeast": "…", "vehicleIds": [], "divisionIds": [], "predicate": null}, "secret": "…", "retryPolicy": {"maxAttempts": 0, "timeoutS": 0, "backoff": "…"}}'

Get a subscription​

GET /v1/webhooks/{id}

  • 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.

Request​

No body.

Response​

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

The same fields as the response of Subscribe a URL to events (secret shown once).

Example​

curl "https://api.zaitrack.app/v1/webhooks/$ID" \
-H "Authorization: Bearer zk_test_…"

Update a subscription​

PATCH /v1/webhooks/{id}

  • Scope: webhooks:write or webhooks:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: low risk
  • Step-up MFA: no
  • If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
urlstringoptional
descriptionstringoptional
eventsarray of string
filtersobjectoptional
filters.severityAtLeaststringoptional
filters.vehicleIdsarray of string (UUID)optional
filters.divisionIdsarray of string (UUID)optional
filters.predicateany JSONoptional
retryPolicyobjectoptional
retryPolicy.maxAttemptsinteger
retryPolicy.timeoutSinteger
retryPolicy.backoffstring
statusstringoptional

Response​

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

The same fields as the response of Subscribe a URL to events (secret shown once).

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/webhooks/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"url": "…", "description": "…"}'

Delete a subscription​

DELETE /v1/webhooks/{id}

  • Scope: webhooks:write or webhooks:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: low risk
  • Step-up MFA: no

Path parameters: id.

Request​

No body.

Response​

204: no body.

Example​

curl -X DELETE "https://api.zaitrack.app/v1/webhooks/$ID" \
-H "Authorization: Bearer zk_test_…"

Send a test event (any public event type with its sample)​

POST /v1/webhooks/{id}:test

  • Scope: webhooks:write or webhooks:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: id.

Request​

Fields the handler reads, taken from its source. One handler serves several actions here, so a field may not apply to this one.

FieldTypeNotes
eventstring

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​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/webhooks/$ID:test" \
-H "Authorization: Bearer zk_test_…" \
-H "Content-Type: application/json" \
-d '{"event": "…"}'

Rotate the signing secret (the old one keeps signing during an overlap)​

POST /v1/webhooks/{id}/secrets:rotate

  • Scope: webhooks:write or webhooks:*
  • Rate class: credentials (10 per minute)
  • Idempotency-Key: optional
  • Audited: high risk
  • Step-up MFA: no

Path parameters: id.

Request​

From the service's OpenAPI document.

FieldTypeNotes
overlapHoursinteger or null

Response​

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

The same fields as the response of Subscribe a URL to events (secret shown once).

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/webhooks/$ID/secrets:rotate" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"overlapHours": 0}'

A subscription's deliveries​

GET /v1/webhooks/{id}/deliveries

  • 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.

Query parameterTypeNotes
statusstring
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/$ID/deliveries" \
-H "Authorization: Bearer zk_test_…"