Webhooks
Third-party integrator subscriptions — see specs/005-api-external-webhooks/. User reads, Admin creates/deletes (FR-019). This service only owns the subscription resource and recent delivery outcomes; webhook-dispatcher is the only writer of a delivery, running as its own deployable service so a slow receiver never touches this API's runtime (FR-008/FR-009).
4 endpoints
Lists an environment's webhook subscriptions. Never another environment's — the read-side of FR-016.
get/v1/environments/{environment_id}/webhooksRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| environment_id* | path | string<uuid> | Environment id |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ListWebhooksResponse | The environment's webhook subscriptions |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No environment with this id exists, or the caller cannot access it |
Registers a webhook subscription. Requires the caller to be an Admin (or above) in the environment.
post/v1/environments/{environment_id}/webhooksRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| environment_id* | path | string<uuid> | Environment id |
Request bodyCreateWebhookRequest
| Field | Type | Description |
|---|---|---|
| event_types* | array<string> | Non-empty, and every member must be a recognized event type (FR-018). |
| signing_secret* | string | Caller-supplied, at least [MIN_SIGNING_SECRET_LEN] characters,
never echoed back (FR-012). |
| target_url* | string | — |
Responses
| Status | Body | Description |
|---|---|---|
| 201 | SubscriptionSummary | The newly registered subscription |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but below Admin |
| 404 | ErrorBody | No environment with this id exists, or the caller cannot access it |
| 422 | ErrorBody | event_types is empty or names an unrecognized type, signing_secret is too short, or target_url fails the SSRF policy |
Removes a webhook subscription and its queued deliveries. Requires the caller to be an Admin (or above) in the environment.
delete/v1/environments/{environment_id}/webhooks/{id}Requires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| environment_id* | path | string<uuid> | Environment id |
| id* | path | string<uuid> | Webhook subscription id |
Responses
| Status | Body | Description |
|---|---|---|
| 204 | — | The subscription is removed |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but below Admin |
| 404 | ErrorBody | No environment or subscription with this id exists, or the caller cannot access it |
Lists a subscription's recent delivery outcomes, newest first.
get/v1/environments/{environment_id}/webhooks/{id}/deliveriesRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| environment_id* | path | string<uuid> | Environment id |
| id* | path | string<uuid> | Webhook subscription id |
| limit | query | integer<int64> | Deliveries per page, capped at 100. Defaults to 20. |
| cursor | query | integer<int64> | Opaque pagination cursor — pass back the previous page's
next_cursor to fetch the next one. Omitted for the first page. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ListDeliveriesResponse | Recent delivery attempts, newest first |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No environment or subscription with this id exists, or the caller cannot access it |