Webhook endpoints

Add a webhook endpoint

POST /v1/webhook_endpoints

The answer carries the signing secret, once.

Permission: webhooks:write

curl -X POST https://api.sw-staging.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer sw_test_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"string"}'

Request body

Field	Type	Required	Description
`description`	string	no	at most 200 characters
`enabled_events`	array of string	no	'', a family such as 'payment.', or exact types; all events unless given. at most 32 items
`url`	string	yes	https URL on the public internet. at most 2048 characters

201 — The endpoint

Field	Type	Description
`created_at`	string (date-time)
`description`	string or null
`enabled_events`	array of string
`environment`	`test`, `live`
`id`	string
`object`	`webhook_endpoint`
`previous_secret_valid_until`	string (date-time) or null
`secret`	string	Shown once: verify signatures with it, store it safely
`status`	`ENABLED`, `DISABLED`
`updated_at`	string (date-time)
`url`	string

Errors answer with the error object.

List webhook endpoints

GET /v1/webhook_endpoints

Permission: webhooks:read

curl -X GET https://api.sw-staging.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer sw_test_…"

200 — The endpoints

Field	Type	Description
`data`	array of object
`data[].created_at`	string (date-time)
`data[].description`	string or null
`data[].enabled_events`	array of string
`data[].environment`	`test`, `live`
`data[].id`	string
`data[].object`	`webhook_endpoint`
`data[].previous_secret_valid_until`	string (date-time) or null
`data[].status`	`ENABLED`, `DISABLED`
`data[].updated_at`	string (date-time)
`data[].url`	string
`object`	`list`

Errors answer with the error object.

Retrieve a webhook endpoint

GET /v1/webhook_endpoints/{id}

Permission: webhooks:read

curl -X GET https://api.sw-staging.dev/v1/webhook_endpoints/pay_01M6XF0H2MAC63MEKQAT4K3AXF \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The endpoint id

200 — The endpoint

Field	Type	Description
`created_at`	string (date-time)
`description`	string or null
`enabled_events`	array of string
`environment`	`test`, `live`
`id`	string
`object`	`webhook_endpoint`
`previous_secret_valid_until`	string (date-time) or null
`status`	`ENABLED`, `DISABLED`
`updated_at`	string (date-time)
`url`	string

Errors answer with the error object.

Stop deliveries to an endpoint

POST /v1/webhook_endpoints/{id}/disable

Permission: webhooks:write

curl -X POST https://api.sw-staging.dev/v1/webhook_endpoints/pay_01M6XF0H2MAC63MEKQAT4K3AXF/disable \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The endpoint id

200 — The endpoint

Field	Type	Description
`created_at`	string (date-time)
`description`	string or null
`enabled_events`	array of string
`environment`	`test`, `live`
`id`	string
`object`	`webhook_endpoint`
`previous_secret_valid_until`	string (date-time) or null
`status`	`ENABLED`, `DISABLED`
`updated_at`	string (date-time)
`url`	string

Errors answer with the error object.

Resume deliveries to an endpoint

POST /v1/webhook_endpoints/{id}/enable

Permission: webhooks:write

curl -X POST https://api.sw-staging.dev/v1/webhook_endpoints/pay_01M6XF0H2MAC63MEKQAT4K3AXF/enable \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The endpoint id

200 — The endpoint

Field	Type	Description
`created_at`	string (date-time)
`description`	string or null
`enabled_events`	array of string
`environment`	`test`, `live`
`id`	string
`object`	`webhook_endpoint`
`previous_secret_valid_until`	string (date-time) or null
`status`	`ENABLED`, `DISABLED`
`updated_at`	string (date-time)
`url`	string

Errors answer with the error object.

Rotate the signing secret

POST /v1/webhook_endpoints/{id}/rotate_secret

A new secret signs from now on; the old one keeps verifying for previous_secret_valid_for_hours, so you can switch without missing a delivery.

Permission: webhooks:write

curl -X POST https://api.sw-staging.dev/v1/webhook_endpoints/pay_01M6XF0H2MAC63MEKQAT4K3AXF/rotate_secret \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The endpoint id

Request body (optional)

Field	Type	Required	Description
`previous_secret_valid_for_hours`	integer	no	How long the old secret keeps verifying (default 24). min 0. max 168

200 — The new secret

Field	Type	Description
`created_at`	string (date-time)
`description`	string or null
`enabled_events`	array of string
`environment`	`test`, `live`
`id`	string
`object`	`webhook_endpoint`
`previous_secret_valid_until`	string (date-time) or null
`secret`	string	Shown once: verify signatures with it, store it safely
`status`	`ENABLED`, `DISABLED`
`updated_at`	string (date-time)
`url`	string

Errors answer with the error object.

An endpoint's recent deliveries

GET /v1/webhook_endpoints/{id}/deliveries

Permission: webhooks:read

curl -X GET https://api.sw-staging.dev/v1/webhook_endpoints/pay_01M6XF0H2MAC63MEKQAT4K3AXF/deliveries \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The endpoint id
`limit`	integer (query)	no	Newest first. default 50. min 1. max 100

200 — The deliveries

Field	Type	Description
`data`	array of object
`data[].attempts`	integer
`data[].created_at`	string (date-time)
`data[].delivered_at`	string (date-time) or null
`data[].event_id`	string
`data[].event_type`	string
`data[].id`	string
`data[].last_error`	string or null
`data[].last_http_status`	integer or null
`data[].next_attempt_at`	string (date-time) or null
`data[].object`	`webhook_delivery`
`data[].status`	`PENDING`, `DELIVERED`, `FAILED`, `DISABLED`
`object`	`list`

Errors answer with the error object.

Send a delivery again

POST /v1/webhook_deliveries/{id}/resend

Permission: webhooks:write

curl -X POST https://api.sw-staging.dev/v1/webhook_deliveries/pay_01M6XF0H2MAC63MEKQAT4K3AXF/resend \
  -H "Authorization: Bearer sw_test_…"

Parameters

Field	Type	Required	Description
`id`	string (path)	yes	The delivery id

202 — Queued again

Field	Type	Description
`id`	string
`status`	`PENDING`

Errors answer with the error object.

Add a webhook endpointCopy Anchor Link

Request bodyCopy Anchor Link

201 — The endpointCopy Anchor Link

List webhook endpointsCopy Anchor Link

200 — The endpointsCopy Anchor Link

Retrieve a webhook endpointCopy Anchor Link

ParametersCopy Anchor Link

200 — The endpointCopy Anchor Link

Stop deliveries to an endpointCopy Anchor Link

ParametersCopy Anchor Link

200 — The endpointCopy Anchor Link

Resume deliveries to an endpointCopy Anchor Link

ParametersCopy Anchor Link

200 — The endpointCopy Anchor Link

Rotate the signing secretCopy Anchor Link

ParametersCopy Anchor Link

Request body (optional)Copy Anchor Link

200 — The new secretCopy Anchor Link

An endpoint's recent deliveriesCopy Anchor Link

ParametersCopy Anchor Link

200 — The deliveriesCopy Anchor Link

Send a delivery againCopy Anchor Link

ParametersCopy Anchor Link

202 — Queued againCopy Anchor Link

On this page

Add a webhook endpoint

Request body

201 — The endpoint

List webhook endpoints

200 — The endpoints

Retrieve a webhook endpoint

Parameters

200 — The endpoint

Stop deliveries to an endpoint

Parameters

200 — The endpoint

Resume deliveries to an endpoint

Parameters

200 — The endpoint

Rotate the signing secret

Parameters

Request body (optional)

200 — The new secret

An endpoint's recent deliveries

Parameters

200 — The deliveries

Send a delivery again

Parameters

202 — Queued again