Webhook endpoints
Register HTTPS endpoints to receive signed event notifications. Each mode (test and live) has its own endpoints and signing secrets.
| get | /v1/webhooksList webhook endpoints | List webhook endpoints |
| post | /v1/webhooksCreate a webhook endpoint | Create a webhook endpoint |
| get | /v1/webhooks/{id}Retrieve a webhook endpoint | Retrieve a webhook endpoint |
| patch | /v1/webhooks/{id}Update a webhook endpoint | Update a webhook endpoint |
| DEL | /v1/webhooks/{id}Delete a webhook endpoint | Delete a webhook endpoint |
| post | /v1/webhooks/{id}/testSend a signed sample event | Send a signed sample event |
| post | /v1/webhooks/{id}/roll-secretRoll the signing secret | Roll the signing secret |
Read the Webhooks guide for the concepts behind these endpoints.
List webhook endpoints
/v1/webhooksResponses
Show response attributesHide response attributes
objectstringrequired | always "list" | ||||||||||||||||||||||
dataarray of objectrequired | Show child attributesHide child attributes
| ||||||||||||||||||||||
has_morebooleanrequired | |||||||||||||||||||||||
next_cursorstring | nullrequired |
Create a webhook endpoint
/v1/webhooksThe response includes the signing secret once. Live endpoints must use HTTPS and resolve to a public IP.
Headers
Idempotency-Keystring | Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response. max length 255 |
Request bodyapplication/json
urlstring (uri)required | max length 2000 |
eventsarray of string | One of |
descriptionstring | max length 200 |
enabledboolean | default true |
Responses
Show response attributesHide response attributes
idstringrequired | |
objectstringrequired | always "webhook_endpoint" |
modestringrequired | One of |
urlstringrequired | |
eventsarray of stringrequired | One of |
descriptionstring | nullrequired | |
enabledbooleanrequired | |
secretstring | Signing secret. Returned only on create. |
disabled_reasonstring | nullrequired | Why the endpoint was disabled automatically, if it was. |
failing_sincestring | nullrequired | When deliveries started failing continuously; null when healthy. |
created_atstringrequired |
Retrieve a webhook endpoint
/v1/webhooks/{id}Path parameters
idstringrequired |
Responses
Show response attributesHide response attributes
idstringrequired | |
objectstringrequired | always "webhook_endpoint" |
modestringrequired | One of |
urlstringrequired | |
eventsarray of stringrequired | One of |
descriptionstring | nullrequired | |
enabledbooleanrequired | |
secretstring | Signing secret. Returned only on create. |
disabled_reasonstring | nullrequired | Why the endpoint was disabled automatically, if it was. |
failing_sincestring | nullrequired | When deliveries started failing continuously; null when healthy. |
created_atstringrequired |
Update a webhook endpoint
/v1/webhooks/{id}Path parameters
idstringrequired |
Request bodyapplication/json
urlstring (uri) | max length 2000 |
eventsarray of string | One of |
descriptionstring | null | |
enabledboolean |
Responses
Show response attributesHide response attributes
idstringrequired | |
objectstringrequired | always "webhook_endpoint" |
modestringrequired | One of |
urlstringrequired | |
eventsarray of stringrequired | One of |
descriptionstring | nullrequired | |
enabledbooleanrequired | |
secretstring | Signing secret. Returned only on create. |
disabled_reasonstring | nullrequired | Why the endpoint was disabled automatically, if it was. |
failing_sincestring | nullrequired | When deliveries started failing continuously; null when healthy. |
created_atstringrequired |
Delete a webhook endpoint
/v1/webhooks/{id}Path parameters
idstringrequired |
Responses
Show response attributesHide response attributes
idstringrequired | |
objectstringrequired | always "webhook_endpoint" |
deletedbooleanrequired | always true |
Send a signed sample event
/v1/webhooks/{id}/testPath parameters
idstringrequired |
Responses
Show response attributesHide response attributes
idstringrequired | |
objectstringrequired | always "webhook_delivery" |
event_idstringrequired | |
event_typestring | nullrequired | |
endpoint_idstringrequired | |
urlstringrequired | |
attemptintegerrequired | |
statusstringrequired | One of |
status_codeinteger | nullrequired | |
latency_msinteger | nullrequired | |
response_bodystring | nullrequired | |
errorstring | nullrequired | |
next_retry_atstring | nullrequired | |
delivered_atstring | nullrequired | |
is_testbooleanrequired | |
created_atstringrequired | |
updated_atstringrequired |
Roll the signing secret
/v1/webhooks/{id}/roll-secretDuring the overlap (default 24 h, max 72 h) every delivery carries two signatures — one per secret — so you can deploy the new secret without dropping events.
Path parameters
idstringrequired |
Request bodyapplication/json
overlap_hoursinteger | 0–72, default 24 |
Responses
Show response attributesHide response attributes
objectstringrequired | always "webhook_secret" |
secretstringrequired | The new signing secret. Shown once. |
previous_secret_expires_atstring | nullrequired | Until this time deliveries are signed with both the new and the previous secret. |