Webhooks API
Signed event delivery to your own endpoints. Register an endpoint, rotate its signing secret, browse the event catalogue, and inspect, test or replay individual deliveries.
On this page
Endpoints#
11 operations, each with its parameters, schemas and an example request on its own page.
- getList webhooks/api/webhooksEvery endpoint in the workspace, or the ones a given agent's events reach.
- postCreate webhook/api/webhooksRegisters an endpoint and returns its signing secret, once.
- getList all deliveries/api/webhooks/deliveriesDeliveries across every endpoint, newest first.
- getGet delivery/api/webhooks/deliveries/{delivery_id}One delivery, with the payload that was actually sent.
- postReplay delivery/api/webhooks/deliveries/{delivery_id}/replayRe-sends a delivery as a new attempt that remembers the original.
- getList events/api/webhooks/eventsThe event catalogue, with a sample payload for each.
- getGet webhook/api/webhooks/{webhook_id}
- patchUpdate webhook/api/webhooks/{webhook_id}Changes URL, events, description or active state.
- deleteDelete webhook/api/webhooks/{webhook_id}
- postRotate secret/api/webhooks/{webhook_id}/rotate-secretIssues a new signing secret. The old one stops working immediately.
- postTest webhook/api/webhooks/{webhook_id}/testFires a synthetic event down the real delivery path.
Authentication#
Every call here needs Authorization: Bearer with a key from the dashboard — Authentication covers keys and scopes.
Objects returned#
The models these endpoints send back, with every field. Open one to read it.
WebhookResponse19 fields
agent_idstring (uuid) | nullrequiredapi_versionstringrequiredconsecutive_failuresintegerrequiredcreated_atstring (date-time)requireddelivery_countintegerrequireddescriptionstring | nullrequireddisabled_atstring (date-time) | nullrequiredeventsarray of stringrequiredfailure_countintegerrequiredhealthstringrequiredOne word for a status dot, derived rather than stored.
Stored health is health that goes stale the moment a delivery lands and nothing recomputes it.
idstring (uuid)requiredis_activebooleanrequiredlast_errorstring | nullrequiredlast_failure_atstring (date-time) | nullrequiredlast_success_atstring (date-time) | nullrequiredorg_idstring (uuid)requiredupdated_atstring (date-time)requiredurlstringrequiredsecret_hintstring | null
WebhookCreated20 fields
agent_idstring (uuid) | nullrequiredapi_versionstringrequiredconsecutive_failuresintegerrequiredcreated_atstring (date-time)requireddelivery_countintegerrequireddescriptionstring | nullrequireddisabled_atstring (date-time) | nullrequiredeventsarray of stringrequiredfailure_countintegerrequiredhealthstringrequiredOne word for a status dot, derived rather than stored.
Stored health is health that goes stale the moment a delivery lands and nothing recomputes it.
idstring (uuid)requiredis_activebooleanrequiredlast_errorstring | nullrequiredlast_failure_atstring (date-time) | nullrequiredlast_success_atstring (date-time) | nullrequiredorg_idstring (uuid)requiredsecretstringrequiredThe signing secret, shown exactly once. Store it now - it cannot be retrieved again, only rotated.
updated_atstring (date-time)requiredurlstringrequiredsecret_hintstring | null
PaginatedResponse_WebhookDeliveryResponse_6 fields
itemsarray of WebhookDeliveryResponserequired12 fieldsWebhookDeliveryResponse
attemptsintegerrequiredcreated_atstring (date-time)requireddelivered_atstring (date-time) | nullrequiredduration_msinteger | nullrequiredeventstringrequiredidstring (uuid)requiredresponse_bodystring | nullrequiredresponse_statusinteger | nullrequiredstatusstringrequiredwebhook_idstring (uuid)requiredpayloadobject | nullreplay_of_idstring (uuid) | null
pageintegerrequiredpage_sizeintegerrequiredtotalintegerrequiredhas_morebooleanDefault: false
next_cursorstring | null
WebhookDeliveryResponse12 fields
attemptsintegerrequiredcreated_atstring (date-time)requireddelivered_atstring (date-time) | nullrequiredduration_msinteger | nullrequiredeventstringrequiredidstring (uuid)requiredresponse_bodystring | nullrequiredresponse_statusinteger | nullrequiredstatusstringrequiredwebhook_idstring (uuid)requiredpayloadobject | nullreplay_of_idstring (uuid) | null
EventDescriptor4 fields
deliverystringrequiredOne of: immediate, batched
descriptionstringrequiredexampleobjectrequirednamestringrequired
Message2 fields
messagestringrequiredokbooleanDefault: true
RotateSecretResponse2 fields
rotated_atstring (date-time)requiredsecretstringrequired
WebhookTestResponse5 fields
delivery_idstring (uuid)requiredokbooleanrequiredduration_msintegerDefault: 0
errorstring | nullstatus_codeinteger | null
Something unclear or missing? Tell us and we’ll fix it.