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: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[].id | — | |
items[].url | — | |
items[].description | — | |
items[].events | — | |
items[].filters | — | |
items[].retryPolicy | object | |
items[].retryPolicy.maxAttempts | integer | |
items[].retryPolicy.timeoutS | integer | |
items[].retryPolicy.backoff | string | |
items[].status | — | |
items[].disabledReason | — | |
items[].consecutiveFailures | — | |
items[].createdBy | — | |
items[].createdAt | string | |
items[].updatedAt | string | |
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:writeorwebhooks:* - 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.
| Field | Type | Notes |
|---|---|---|
url | string | |
description | string | |
events | array of string | |
filters | object | |
filters.severityAtLeast | string | optional |
filters.vehicleIds | array of string (UUID) | optional |
filters.divisionIds | array of string (UUID) | optional |
filters.predicate | any JSON | optional |
secret | string | |
retryPolicy | object | |
retryPolicy.maxAttempts | integer | |
retryPolicy.timeoutS | integer | |
retryPolicy.backoff | string |
Response
201: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
id | — | |
url | — | |
description | — | |
events | — | |
filters | object | |
filters.severityAtLeast | — | |
filters.vehicleIds | array | |
filters.divisionIds | array | |
retryPolicy | object | |
retryPolicy.maxAttempts | integer | |
retryPolicy.timeoutS | integer | |
retryPolicy.backoff | string | |
status | — | |
disabledReason | — | |
consecutiveFailures | — | |
createdBy | — | |
createdAt | string | |
updatedAt | string | |
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: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.
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:writeorwebhooks:* - 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.
| Field | Type | Notes |
|---|---|---|
url | string | optional |
description | string | optional |
events | array of string | |
filters | object | optional |
filters.severityAtLeast | string | optional |
filters.vehicleIds | array of string (UUID) | optional |
filters.divisionIds | array of string (UUID) | optional |
filters.predicate | any JSON | optional |
retryPolicy | object | optional |
retryPolicy.maxAttempts | integer | |
retryPolicy.timeoutS | integer | |
retryPolicy.backoff | string | |
status | string | optional |
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:writeorwebhooks:* - 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:writeorwebhooks:* - 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.
| Field | Type | Notes |
|---|---|---|
event | string |
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
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:writeorwebhooks:* - 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.
| Field | Type | Notes |
|---|---|---|
overlapHours | integer 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: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.
| Query parameter | Type | Notes |
|---|---|---|
status | string | |
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/$ID/deliveries" \
-H "Authorization: Bearer zk_test_…"