Webhooks

API reference descriptions are provided in English to preserve the exact published contract.

Redeliver a selection of retained events

POST /v1/accounts/{AC}/events/redeliver

postV1AccountsByAcEventsRedeliverIdempotency-Key required202

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (2 fields)

Request body
Name	Type	Required	Description
`endpointSid`	string (WH… SID)
`eventSids`	string (EV… SID)[]	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Redeliver a retained event to its subscribed endpoints (DEV-017)

POST /v1/accounts/{AC}/events/{EV}/redeliver

postV1AccountsByAcEventsByEvRedeliverIdempotency-Key required202

Send a retained event again, to every subscribed endpoint or to one with `endpointSid`. Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`EV`	path · string (EV… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`endpointSid`	string (WH… SID)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List webhook deliveries for one retained resource

GET /v1/accounts/{AC}/webhook-deliveries

getV1AccountsByAcWebhookDeliveriesPaginated200

Required scope: `webhooks:read`.

Parameters

Parameters
Name	Type	Required	Description
`resourceSid`	query · string (max 128 chars)	yes
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List the event types a webhook endpoint can subscribe to

GET /v1/accounts/{AC}/webhook-event-types

getV1AccountsByAcWebhookEventTypes200

Required scope: `webhooks:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List customer webhook endpoints

GET /v1/accounts/{AC}/webhooks

getV1AccountsByAcWebhooksPaginated200

List your webhook endpoints with their verification and delivery state. Required scope: `webhooks:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a customer webhook endpoint

POST /v1/accounts/{AC}/webhooks

postV1AccountsByAcWebhooksIdempotency-Key required201

Register an HTTPS endpoint for events. It receives nothing until verified. Needs a recent step-up (`stepUpToken`). Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (6 fields)

Request body
Name	Type	Required
`apiVersion`	string (pattern ^\d{4}-\d{2}-\d{2}$)
`concurrencyCap`	integer (1–256)
`eventFilters`	string (max 128 chars)[]
`stepUpToken`	string (max 256 chars)
`timeoutMs`	integer (1000–30000)
`url`	string (uri, max 2048 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch a customer webhook endpoint

GET /v1/accounts/{AC}/webhooks/{WH}

getV1AccountsByAcWebhooksByWh200

Required scope: `webhooks:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update a customer webhook endpoint

PATCH /v1/accounts/{AC}/webhooks/{WH}

patchV1AccountsByAcWebhooksByWhIdempotency-Key required200

Change an endpoint's URL, event filters, timeout or concurrency. Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Request body (6 fields)

Request body
Name	Type	Required	Description
`apiVersion`	string (pattern ^\d{4}-\d{2}-\d{2}$)
`concurrencyCap`	integer (1–256)
`eventFilters`	string (max 128 chars)[]
`stepUpToken`	string (max 256 chars)
`timeoutMs`	integer (1000–30000)
`url`	string (uri, max 2048 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Disable a customer webhook endpoint

DELETE /v1/accounts/{AC}/webhooks/{WH}

deleteV1AccountsByAcWebhooksByWh204

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List webhook delivery history

GET /v1/accounts/{AC}/webhooks/{WH}/deliveries

getV1AccountsByAcWebhooksByWhDeliveriesPaginated200

Required scope: `webhooks:read`.

Parameters

Parameters
Name	Type	Required
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`sort`	query · "createdAt" \| "-createdAt"
`resourceSid`	query · string (max 128 chars)
`eventId`	query · string (EV… SID)
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Retry queued or failed webhook deliveries, oldest first

POST /v1/accounts/{AC}/webhooks/{WH}/deliveries/retry

postV1AccountsByAcWebhooksByWhDeliveriesRetryIdempotency-Key required202

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`deliverySids`	string (WD… SID)[]
`state`	"pending" \| "failed"

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch webhook delivery request and attempt history

GET /v1/accounts/{AC}/webhooks/{WH}/deliveries/{WD}

getV1AccountsByAcWebhooksByWhDeliveriesByWd200

Required scope: `webhooks:read`.

Parameters

Parameters
Name	Type	Required
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes
`WD`	path · string (WD… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Redeliver a retained event without reprocessing its resource

POST /v1/accounts/{AC}/webhooks/{WH}/deliveries/{WD}/retry

postV1AccountsByAcWebhooksByWhDeliveriesByWdRetryIdempotency-Key required202

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes
`WD`	path · string (WD… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Pause endpoint delivery

POST /v1/accounts/{AC}/webhooks/{WH}/pause

postV1AccountsByAcWebhooksByWhPauseIdempotency-Key required200

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Resume endpoint delivery

POST /v1/accounts/{AC}/webhooks/{WH}/resume

postV1AccountsByAcWebhooksByWhResumeIdempotency-Key required200

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

End the signing-secret rotation overlap immediately

POST /v1/accounts/{AC}/webhooks/{WH}/secret/end-overlap

postV1AccountsByAcWebhooksByWhSecretEndOverlapIdempotency-Key required200

Expires the previous signing secret now. Deliveries stop carrying its `v1=` signature, so any integration still verifying with the old secret fails from this moment. Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Rotate the endpoint signing secret with overlap

POST /v1/accounts/{AC}/webhooks/{WH}/secret/rotate

postV1AccountsByAcWebhooksByWhSecretRotateIdempotency-Key required200

Issue a new signing secret. The old one keeps signing alongside it until `expiresAt`, so you can deploy the new one without dropping events. Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`expiresAt`	string (date-time)
`stepUpToken`	string (max 256 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Send a signed test.ping event

POST /v1/accounts/{AC}/webhooks/{WH}/test

postV1AccountsByAcWebhooksByWhTestIdempotency-Key required200

Send a signed `test.ping` event to the endpoint and report how it answered. Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Verify endpoint ownership and activate delivery

POST /v1/accounts/{AC}/webhooks/{WH}/verify

postV1AccountsByAcWebhooksByWhVerifyIdempotency-Key required200

Required scope: `webhooks:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WH`	path · string (WH… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.