API reference
Webhooks
Signed Standard Webhooks deliveries of the public events to your endpoints.
GET/webhook-endpoints
List webhook endpoints
- Scope webhooks:read
Endpoints in the credential's mode and brands, each with its status and newest delivery.
curl https://api.relayport.dev/webhook-endpoints \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
limitintegerquerycursorstringquery
Responses
200OK
dataWebhookEndpoint[]requiredidstring (uuid)requiredurlstringrequireddescriptionstring | nullrequiredeventsstring[]requiredbrandIds(string (uuid))[]requiredaccountIds(string (uuid))[]requiredlivemodebooleanrequiredstatusstringrequiredOne of
activefailingdisabledconsecutiveFailuresintegerrequiredfailingSincestring (date-time) | nullrequiredapiVersionstringrequiredlastDeliveryobject | nullrequiredThe newest delivery to this endpoint, or null when it has none
statusstringrequiredOne of
pendingsendingsuccessfailedskippedatstring (date-time)requiredcreatedAtstring (date-time)requiredmetaPageMetarequirednext_cursorstring | nullrequiredper_pageintegerrequired
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
POST/webhook-endpoints
Create a webhook endpoint
- Scope webhooks:write
A public HTTPS URL and the events it receives: event types, prefixes ending in .* or *. The response carries the signing secret (whsec_...) once. An API key creates endpoints in its own mode; a brand-restricted key must limit the endpoint to its brands. At most 20 endpoints per workspace (409 Conflict with details.reason endpoint_limit).
curl -X POST https://api.relayport.dev/webhook-endpoints \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "<string>", "events": ["<string>"] }'Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
Idempotency-KeystringheaderOnly blocks a second request with the same key while the first runs (409 IdempotencyInProgress). The response carries a secret, so it is never stored or replayed: a retry with the same key runs again and issues a new secret.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequest
Request body
urlstringrequiredeventsstring[]requireddescriptionstringbrandIds(string (uuid))[]accountIds(string (uuid))[]livemodeboolean
Responses
201Created
dataIssuedWebhookEndpointrequiredidstring (uuid)requiredurlstringrequireddescriptionstring | nullrequiredeventsstring[]requiredbrandIds(string (uuid))[]requiredaccountIds(string (uuid))[]requiredlivemodebooleanrequiredstatusstringrequiredOne of
activefailingdisabledconsecutiveFailuresintegerrequiredfailingSincestring (date-time) | nullrequiredapiVersionstringrequiredlastDeliveryobject | nullrequiredThe newest delivery to this endpoint, or null when it has none
statusstringrequiredOne of
pendingsendingsuccessfailedskippedatstring (date-time)requiredcreatedAtstring (date-time)requiredsecretstringrequiredThe signing secret (whsec_...), shown once
400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409ConflictIdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable
GET/webhook-endpoints/{id}
Get a webhook endpoint
- Scope webhooks:read
curl https://api.relayport.dev/webhook-endpoints/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
idstring (uuid)pathrequired
Responses
200OK
dataWebhookEndpointrequiredidstring (uuid)requiredurlstringrequireddescriptionstring | nullrequiredeventsstring[]requiredbrandIds(string (uuid))[]requiredaccountIds(string (uuid))[]requiredlivemodebooleanrequiredstatusstringrequiredOne of
activefailingdisabledconsecutiveFailuresintegerrequiredfailingSincestring (date-time) | nullrequiredapiVersionstringrequiredlastDeliveryobject | nullrequiredThe newest delivery to this endpoint, or null when it has none
statusstringrequiredOne of
pendingsendingsuccessfailedskippedatstring (date-time)requiredcreatedAtstring (date-time)required
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
PATCH/webhook-endpoints/{id}
Update a webhook endpoint
- Scope webhooks:write
Set status disabled to pause deliveries, or active to resume them. An endpoint that fails for 3 days is failing, and after 7 days it is disabled.
curl -X PATCH https://api.relayport.dev/webhook-endpoints/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Request body
urlstringeventsstring[]descriptionstring | nullbrandIds(string (uuid))[]accountIds(string (uuid))[]statusstringOne of
activedisabled
Responses
200OK
dataWebhookEndpointrequiredidstring (uuid)requiredurlstringrequireddescriptionstring | nullrequiredeventsstring[]requiredbrandIds(string (uuid))[]requiredaccountIds(string (uuid))[]requiredlivemodebooleanrequiredstatusstringrequiredOne of
activefailingdisabledconsecutiveFailuresintegerrequiredfailingSincestring (date-time) | nullrequiredapiVersionstringrequiredlastDeliveryobject | nullrequiredThe newest delivery to this endpoint, or null when it has none
statusstringrequiredOne of
pendingsendingsuccessfailedskippedatstring (date-time)requiredcreatedAtstring (date-time)required
400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
DELETE/webhook-endpoints/{id}
Delete a webhook endpoint
- Scope webhooks:write
curl -X DELETE https://api.relayport.dev/webhook-endpoints/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Responses
204No Content
No fields.
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
GET/webhook-endpoints/{id}/deliveries
List an endpoint's delivery attempts
- Scope webhooks:read
Newest first, with the response status, a response excerpt and the next retry time. A failed attempt is retried 10 times with backoff.
curl https://api.relayport.dev/webhook-endpoints/{id}/deliveries \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
idstring (uuid)pathrequiredlimitintegerquerycursorstringquerystatusstringqueryOne of
pendingsendingsuccessfailedskippedeventIdstring (uuid)query
Responses
200OK
dataWebhookDelivery[]requiredidstring (uuid)requiredendpointIdstring (uuid)requiredeventIdstring (uuid)requiredeventTypestringrequiredattemptintegerrequiredtriggerstringrequiredOne of
automanualteststatusstringrequiredOne of
pendingsendingsuccessfailedskippedresponseStatusinteger | nullrequiredresponseExcerptstring | nullrequireddurationMsinteger | nullrequirednextAttemptAtstring (date-time) | nullrequiredcreatedAtstring (date-time)requiredmetaPageMetarequirednext_cursorstring | nullrequiredper_pageintegerrequired
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
POST/webhook-endpoints/{id}/deliveries/{deliveryId}/retry
Send a delivery's event again
- Scope webhooks:write
- Idempotency-Key
Queues a new attempt of the delivery's event to the endpoint. 409 Conflict while the endpoint is disabled (details.reason endpoint_disabled) or the event is being delivered right now (delivery_sending).
curl -X POST https://api.relayport.dev/webhook-endpoints/{id}/deliveries/{deliveryId}/retry \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
Idempotency-KeystringheaderRepeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequireddeliveryIdstring (uuid)pathrequired
Request body
Content types application/json
Responses
202Accepted
dataWebhookDeliveryrequiredidstring (uuid)requiredendpointIdstring (uuid)requiredeventIdstring (uuid)requiredeventTypestringrequiredattemptintegerrequiredtriggerstringrequiredOne of
automanualteststatusstringrequiredOne of
pendingsendingsuccessfailedskippedresponseStatusinteger | nullrequiredresponseExcerptstring | nullrequireddurationMsinteger | nullrequirednextAttemptAtstring (date-time) | nullrequiredcreatedAtstring (date-time)required
400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409ConflictIdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable
POST/webhook-endpoints/{id}/rotate-secret
Rotate a webhook endpoint's signing secret
- Scope webhooks:write
Returns the new secret once. For overlapHours (default 24, at most 168) each delivery is signed with both secrets, so the webhook-signature header carries two signatures.
curl -X POST https://api.relayport.dev/webhook-endpoints/{id}/rotate-secret \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
Idempotency-KeystringheaderOnly blocks a second request with the same key while the first runs (409 IdempotencyInProgress). The response carries a secret, so it is never stored or replayed: a retry with the same key runs again and issues a new secret.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Request body
overlapHoursinteger
Responses
200OK
dataIssuedWebhookEndpointrequiredidstring (uuid)requiredurlstringrequireddescriptionstring | nullrequiredeventsstring[]requiredbrandIds(string (uuid))[]requiredaccountIds(string (uuid))[]requiredlivemodebooleanrequiredstatusstringrequiredOne of
activefailingdisabledconsecutiveFailuresintegerrequiredfailingSincestring (date-time) | nullrequiredapiVersionstringrequiredlastDeliveryobject | nullrequiredThe newest delivery to this endpoint, or null when it has none
statusstringrequiredOne of
pendingsendingsuccessfailedskippedatstring (date-time)requiredcreatedAtstring (date-time)requiredsecretstringrequiredThe signing secret (whsec_...), shown once
400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409ConflictIdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable
POST/webhook-endpoints/{id}/test
Send a webhook.test event to an endpoint
- Scope webhooks:write
- Idempotency-Key
curl -X POST https://api.relayport.dev/webhook-endpoints/{id}/test \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'Parameters
X-Api-VersionstringheaderThe API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.
One of
2026-12-01X-Workspace-Idstring (uuid)headerThe workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.
Idempotency-KeystringheaderRepeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Request body
Content types application/json
Responses
201Created
dataWebhookDeliveryrequiredidstring (uuid)requiredendpointIdstring (uuid)requiredeventIdstring (uuid)requiredeventTypestringrequiredattemptintegerrequiredtriggerstringrequiredOne of
automanualteststatusstringrequiredOne of
pendingsendingsuccessfailedskippedresponseStatusinteger | nullrequiredresponseExcerptstring | nullrequireddurationMsinteger | nullrequirednextAttemptAtstring (date-time) | nullrequiredcreatedAtstring (date-time)required