Webhook Deliveries API

Every event Subscriby posts to one of your webhook endpoints is a delivery: one row per endpoint per event, carrying the signed envelope that was sent, the target's response and where the row is on the retry ladder.

Every event Subscriby posts to one of your webhook endpoints is a delivery: one row per endpoint per event, carrying the signed envelope that was sent, the target's response and where the row is on the retry ladder. This is the same log the dashboard shows under Settings → Webhook Deliveries, over REST, so an integrator on call can see why a consumer rejected an event without signing in.

The two replay paths are the dashboard's too. A single failed or dead-lettered row can be retried from the start of the ladder, and everything the team dead-lettered since an instant can be replayed at once after a fix. A token that still carries the retired webhook-endpoint:manage satisfies both abilities on this page; see the ability catalog.

Endpoints

GET/v1/webhook-deliveriesList webhook deliveries GET/v1/webhook-deliveries/{delivery}Get a webhook delivery POST/v1/webhook-deliveries/retry-deadRetry every recent dead delivery POST/v1/webhook-deliveries/{delivery}/retryRetry a webhook delivery

List webhook deliveries

GET

curl "https://api.subscriby.net/v1/webhook-deliveries?status=dead" \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

The team's deliveries across every endpoint, newest first, 25 per page (per_page 1 to 100; limit is accepted as an alias).

Requires ability

webhook-delivery:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_webhook_deliveries

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Query Parameters

status?|

One of the log's tabs: all (the default), pending, delivered, failed or dead. A tab rather than a raw status, so an omitted value lists every row instead of quietly matching nothing. Anything else is refused.

page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value

Default1

per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 15.

Range1 <= value <= 100

Default15

sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"

sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

"asc"
"desc"

limit?integer

Legacy alias of per_page, kept for clients that predate it. per_page wins when both are sent.

Range1 <= value <= 100

Responses

200OKapplication/json

The tenant's deliveries on that tab, newest first.

data*array<>

The items on this page.

links*

Links to the first, last, previous and next pages.

meta*

The paging counters for this page.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: naming status when it is not one of the five tabs.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/webhook-deliveries"

{  "data": [    {      "id": "34f1d78e-05a2-4b69-8c3d-7e921ab06f45",      "endpoint_id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",      "event": "subscription.created",      "event_id": "01HXZ3Q8M7Y2K4N6P9R1T3V5W7",      "status": "failed",      "attempts": 2,      "response_status": 500,      "response_excerpt": "upstream unavailable",      "payload": [        null      ],      "next_attempt_at": "2026-09-06T10:15:00+00:00",      "delivered_at": null,      "dead_lettered_at": null,      "created_at": "2026-09-06T10:05:00+00:00"    }  ],  "links": {    "first": "string",    "last": "string",    "prev": "string",    "next": "string"  },  "meta": {    "current_page": 1,    "from": 1,    "last_page": 1,    "links": [      {        "url": "string",        "label": "string",        "active": true      }    ],    "path": "string",    "per_page": 0,    "to": 1,    "total": 0  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: WebhookDeliveryResource[];  links: Links;  meta: Meta;}export interface WebhookDeliveryResource {  id: string;  endpoint_id: string;  event: string;  event_id: string;  status: string;  attempts: number;  response_status: number | null;  response_excerpt: string | null;  payload: unknown[];  next_attempt_at: string | null;  delivered_at: string | null;  dead_lettered_at: string | null;  created_at: string;}export interface Links {  first: string | null;  last: string | null;  prev: string | null;  next: string | null;}export interface Meta {  current_page: number;  from: number | null;  last_page: number;  links: Link[];  path: string | null;  per_page: number;  to: number | null;  total: number;}export interface Link {  url: string | null;  label: string;  active: boolean;}

Get a webhook delivery

GET

curl https://api.subscriby.net/v1/webhook-deliveries/$DELIVERY_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

One delivery. Another team's delivery is a 404 RESOURCE_NOT_FOUND, never a 403.

Field	Type	Notes
`event`	string	The event name, as in the catalog.
`event_id`	string	The 26-character ULID the envelope's `id` carries without its `evt_` prefix; also the `SB-Event-Id` header your handler received.
`status`	string	`pending`, `delivered`, `failed` or `dead`. See below.
`attempts`	integer	Posts made so far. Reset to `0` by a retry.
`response_status`	integer or null	The HTTP status your endpoint returned on the last attempt; `null` before the first post or after a transport failure.
`response_excerpt`	string or null	The start of the response body, or the transport error.
`payload`	object	The full event envelope that was, or would have been, posted, so a consumer can be debugged against it exactly.
`next_attempt_at`	string or null	When the worker will post a `failed` row again.
`delivered_at`	string or null	Stamped on the first 2xx.
`dead_lettered_at`	string or null	Stamped when the ladder ran out.

There is no updated_at: a delivery only moves forward through its statuses, and the three timestamps say when each transition happened.

A row is born pending, becomes failed after a non-2xx or transport error while retries remain, delivered on the first 2xx, and dead once the ladder is exhausted or the endpoint vanished. delivered and dead are final until a retry resets the row to pending.

payload discloses nothing new. The envelope is what your own endpoint already received, or would have had it answered. Reading it needs webhook-delivery:view-any, and the tenant scope reaches a delivery only through an endpoint of the token's team.

Requires ability

webhook-delivery:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

get_webhook_delivery

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

delivery*string

The delivery, resolved by the route binder.

Formatuuid

Responses

200OKapplication/json

The delivery with the envelope its endpoint received.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/webhook-deliveries/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "34f1d78e-05a2-4b69-8c3d-7e921ab06f45",    "endpoint_id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",    "event": "subscription.created",    "event_id": "01HXZ3Q8M7Y2K4N6P9R1T3V5W7",    "status": "failed",    "attempts": 2,    "response_status": 500,    "response_excerpt": "upstream unavailable",    "payload": {      "id": "evt_01HXZ3Q8M7Y2K4N6P9R1T3V5W7",      "type": "subscription.created",      "created_at": "2026-09-06T10:05:00+00:00",      "api_version": "2026-05-01",      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "data": {        "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",        "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",        "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80"      }    },    "next_attempt_at": "2026-09-06T10:15:00+00:00",    "delivered_at": null,    "dead_lettered_at": null,    "created_at": "2026-09-06T10:05:00+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: WebhookDeliveryResource;}export interface WebhookDeliveryResource {  id: string;  endpoint_id: string;  event: string;  event_id: string;  status: string;  attempts: number;  response_status: number | null;  response_excerpt: string | null;  payload: unknown[];  next_attempt_at: string | null;  delivered_at: string | null;  dead_lettered_at: string | null;  created_at: string;}

Retry every recent dead delivery

POST

Once the consumer is fixed, replay everything the team dead-lettered since an instant in one call.

curl -X POST https://api.subscriby.net/v1/webhook-deliveries/retry-dead \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"since": "2026-09-05T22:00:00Z"}'

retried is how many rows were reset and queued. Only dead rows are touched: a failed row is still on its ladder and will be posted again on its own. The replay is capped at 500 rows per call so one request after a long outage cannot flood the queue or the target; call it again if the count comes back at the ceiling.

Each replayed row posts its event again, so confirm the consumer is healthy first; see replaying bulk dead deliveries.

Requires ability

webhook-delivery:retry

The token must hold this ability, or the call is refused with 403.

MCP tool

retry_dead_webhook_deliveries

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesOptionalapplication/json

How far back to replay. Optional: omitted, the last 24 hours are replayed, the dashboard's Replay window.

since?|

ISO 8601, not in the future. Only rows dead-lettered at or after this instant are replayed. Omit it for the last 24 hours.

Formatdate-time

Responses

200OKapplication/json

How many rows were re-queued and the instant the window opened at.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/webhook-deliveries/retry-dead" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "retried": 17,    "since": "2026-09-05T22:00:00+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface RetryDeadWebhookDeliveriesRequest {  since?: string | null;}

Response

export interface Response {  data: Data;}export interface Data {  retried: number;  since: string;}

Retry a webhook delivery

POST

curl -X POST https://api.subscriby.net/v1/webhook-deliveries/$DELIVERY_ID/retry \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Answers 200 with the row pending again: attempts back to 0, response_status, response_excerpt and dead_lettered_at cleared, and the worker queued. The delivery log then shows the replay's own outcome rather than the original failure's. A retry re-posts the original event to its endpoint; nothing new is raised about the replay itself.

Only failed and dead rows can be retried. Resetting a delivered row would post the event to your server a second time. The dashboard hides its retry button behind the same rule, but a row can be delivered between a render and a click, and the API has no button at all.

Requires ability

webhook-delivery:retry

The token must hold this ability, or the call is refused with 403.

MCP tool

retry_webhook_delivery

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

delivery*string

The delivery, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

200OKapplication/json

The delivery, pending again.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

For a pending or delivered row, with the message *Only failed or dead-lettered deliveries can be retried.*

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/webhook-deliveries/497f6eca-6276-4993-bfeb-53cbbbba6f08/retry" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "id": "34f1d78e-05a2-4b69-8c3d-7e921ab06f45",    "endpoint_id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",    "event": "subscription.created",    "event_id": "01HXZ3Q8M7Y2K4N6P9R1T3V5W7",    "status": "failed",    "attempts": 2,    "response_status": 500,    "response_excerpt": "upstream unavailable",    "payload": [      null    ],    "next_attempt_at": "2026-09-06T10:15:00+00:00",    "delivered_at": null,    "dead_lettered_at": null,    "created_at": "2026-09-06T10:05:00+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: WebhookDeliveryResource;}export interface WebhookDeliveryResource {  id: string;  endpoint_id: string;  event: string;  event_id: string;  status: string;  attempts: number;  response_status: number | null;  response_excerpt: string | null;  payload: unknown[];  next_attempt_at: string | null;  delivered_at: string | null;  dead_lettered_at: string | null;  created_at: string;}

Webhook Endpoints APIThe targets these deliveries were posted to; pause one while you fix it.Webhook Events APIThe polling view of recent deliveries by event type.Retries & DeliveryThe ladder, dead-lettering and auto-disable.Testing & Debugging WebhooksFire a test payload, inspect the delivery log, and manually retry failed deliveries without waiting for the production trigger.

Webhook Deliveries API

EndpointsCopy Anchor Link

List webhook deliveriesCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Get a webhook deliveryCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Retry every recent dead deliveryCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Retry a webhook deliveryCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

Endpoints

List webhook deliveries

Authorization

Query Parameters

Responses

Get a webhook delivery

Authorization

Path Parameters

Responses

Retry every recent dead delivery

Authorization

Header Parameters

Request body

Responses

Retry a webhook delivery

Authorization

Path Parameters

Header Parameters

Responses