Skip to content

Webhooks

A workspace's webhook endpoints, the events they hear about, and every delivery and attempt, with resend, replay and test. Events name what changed and never carry a value. See the Webhooks guide for the event catalogue and signature check.

GET /api/webhooks/event-types

List the event types

Auth: ApiKey, Session

The catalogue an endpoint subscribes from. noisy types are left out of "*". privateCallbacks says whether this server delivers to loopback and private addresses (ALLOW_PRIVATE_CALLBACKS); when it is false, an endpoint at such an address is refused.

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

Response fields

Field Type Notes
items array of object
privateCallbacks boolean

GET /api/webhooks/endpoints

List webhook endpoints

Auth: ApiKey, Session

Every endpoint in the active workspace, with the last day's stats. Never includes the secret.

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

POST /api/webhooks/endpoints

Create a webhook endpoint

Auth: ApiKey, Session

events defaults to ["*"]. The answer carries the signing secret.

Request body

application/json

Field Type Notes
url string
description string
events array of string
enabled boolean

Responses

Status Meaning
201 The endpoint, with secret.
403 The caller lacks Manage webhooks (webhooks:manage).

GET /api/webhooks/endpoints/{id}/metrics

How an endpoint has done

Auth: ApiKey, Session

Its attempts over range (1h in 5-minute buckets, 24h hourly, the default, or 7d in 6-hour buckets), oldest first: how many were answered with a 2xx and how many weren't, with the median and p95 response time. Also the range's answers by kind (2xx, 4xx, 5xx, none for no answer), the deliveries made and how many got through on the first try, how many wait to be tried again right now, and the event types sent most. The endpoint list carries the last day as series.

Parameters

Name In Required Notes
id path yes
range query no

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).
404 Not an endpoint of this workspace.

Response fields

Field Type Notes
range string
buckets array of object
deliveries integer
firstTry integer
retrying integer
p95Ms integer
codes object
events array of object

GET /api/webhooks/endpoints/{id}

Get a webhook endpoint

Auth: ApiKey, Session

One endpoint, with the last day's stats.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

PATCH /api/webhooks/endpoints/{id}

Change a webhook endpoint

Auth: ApiKey, Session

Any of url, description, events, enabled. Turning it on clears the failing clock.

Parameters

Name In Required Notes
id path yes

Request body

application/json

Field Type Notes
url string
description string
events array of string
enabled boolean

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

DELETE /api/webhooks/endpoints/{id}

Delete a webhook endpoint

Auth: ApiKey, Session

Deletes the endpoint and its delivery log.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
204 Deleted.
403 The caller lacks Manage webhooks (webhooks:manage).

GET /api/webhooks/endpoints/{id}/secret

Show the signing secret

Auth: ApiKey, Session

The current secret, for setting up the receiving side.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

POST /api/webhooks/endpoints/{id}/rotate-secret

Rotate the signing secret

Auth: ApiKey, Session

A new secret. The previous one keeps signing alongside it for 24 hours.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

POST /api/webhooks/endpoints/{id}/test

Send a test event

Auth: ApiKey, Session

Sends one sample of type now, once, marked test: true, and answers with the delivery.

Parameters

Name In Required Notes
id path yes

Request body

application/json

Field Type Notes
type string

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

POST /api/webhooks/endpoints/{id}/replay

Resend failed deliveries

Auth: ApiKey, Session

Queues every failed delivery since since (RFC 3339, default 24 hours ago) again. Answers { queued }.

Parameters

Name In Required Notes
id path yes

Request body

application/json

Field Type Notes
since string

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

GET /api/webhooks/events

List events

Auth: ApiKey, Session

The workspace's events, newest first. Filter with type; page with page and perPage.

Parameters

Name In Required Notes
page query no
perPage query no
type query no An event type from /api/webhooks/event-types.

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

GET /api/webhooks/deliveries

List deliveries

Auth: ApiKey, Session

Newest first. Filter with endpoint, status (pending, succeeded, failed), type or event.

Parameters

Name In Required Notes
page query no
perPage query no
endpoint query no An endpoint id.
status query no
type query no An event type.
event query no An event id.

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

GET /api/webhooks/deliveries/{id}

Get a delivery

Auth: ApiKey, Session

The delivery with its payload and attemptLog: each attempt's status, response body (first 2 KB), error and duration.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).

POST /api/webhooks/deliveries/{id}/resend

Resend a delivery

Auth: ApiKey, Session

Tries it once more now. Success marks it delivered; failure leaves the automatic retries unchanged.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 OK
403 The caller lacks Manage webhooks (webhooks:manage).