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