Skip to content
Relay Port

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.

Request
curl https://api.relayport.dev/webhook-endpoints \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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.

  • limitintegerquery

  • cursorstringquery

Responses

200OK
  • dataWebhookEndpoint[]required

  • idstring (uuid)required

  • urlstringrequired

  • descriptionstring | nullrequired

  • eventsstring[]required

  • brandIds(string (uuid))[]required

  • accountIds(string (uuid))[]required

  • livemodebooleanrequired

  • statusstringrequired

    One of active failing disabled

  • consecutiveFailuresintegerrequired

  • failingSincestring (date-time) | nullrequired

  • apiVersionstringrequired

  • lastDeliveryobject | nullrequired

    The newest delivery to this endpoint, or null when it has none

  • statusstringrequired

    One of pending sending success failed skipped

  • atstring (date-time)required

  • createdAtstring (date-time)required

  • metaPageMetarequired

  • next_cursorstring | nullrequired

  • per_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).

Request
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-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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-Keystringheader

    Only 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-Withstringheader

    Required 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

  • urlstringrequired

  • eventsstring[]required

  • descriptionstring

  • brandIds(string (uuid))[]

  • accountIds(string (uuid))[]

  • livemodeboolean

Responses

201Created
  • dataIssuedWebhookEndpointrequired

  • idstring (uuid)required

  • urlstringrequired

  • descriptionstring | nullrequired

  • eventsstring[]required

  • brandIds(string (uuid))[]required

  • accountIds(string (uuid))[]required

  • livemodebooleanrequired

  • statusstringrequired

    One of active failing disabled

  • consecutiveFailuresintegerrequired

  • failingSincestring (date-time) | nullrequired

  • apiVersionstringrequired

  • lastDeliveryobject | nullrequired

    The newest delivery to this endpoint, or null when it has none

  • statusstringrequired

    One of pending sending success failed skipped

  • atstring (date-time)required

  • createdAtstring (date-time)required

  • secretstringrequired

    The 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
Request
curl https://api.relayport.dev/webhook-endpoints/{id} \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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
  • dataWebhookEndpointrequired

  • idstring (uuid)required

  • urlstringrequired

  • descriptionstring | nullrequired

  • eventsstring[]required

  • brandIds(string (uuid))[]required

  • accountIds(string (uuid))[]required

  • livemodebooleanrequired

  • statusstringrequired

    One of active failing disabled

  • consecutiveFailuresintegerrequired

  • failingSincestring (date-time) | nullrequired

  • apiVersionstringrequired

  • lastDeliveryobject | nullrequired

    The newest delivery to this endpoint, or null when it has none

  • statusstringrequired

    One of pending sending success failed skipped

  • atstring (date-time)required

  • createdAtstring (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.

Request
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-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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-Withstringheader

    Required 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

  • idstring (uuid)pathrequired

Request body

  • urlstring

  • eventsstring[]

  • descriptionstring | null

  • brandIds(string (uuid))[]

  • accountIds(string (uuid))[]

  • statusstring

    One of active disabled

Responses

200OK
  • dataWebhookEndpointrequired

  • idstring (uuid)required

  • urlstringrequired

  • descriptionstring | nullrequired

  • eventsstring[]required

  • brandIds(string (uuid))[]required

  • accountIds(string (uuid))[]required

  • livemodebooleanrequired

  • statusstringrequired

    One of active failing disabled

  • consecutiveFailuresintegerrequired

  • failingSincestring (date-time) | nullrequired

  • apiVersionstringrequired

  • lastDeliveryobject | nullrequired

    The newest delivery to this endpoint, or null when it has none

  • statusstringrequired

    One of pending sending success failed skipped

  • atstring (date-time)required

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable

DELETE/webhook-endpoints/{id}

Delete a webhook endpoint

  • Scope webhooks:write
Request
curl -X DELETE https://api.relayport.dev/webhook-endpoints/{id} \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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-Withstringheader

    Required 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

  • idstring (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.

Request
curl https://api.relayport.dev/webhook-endpoints/{id}/deliveries \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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

  • limitintegerquery

  • cursorstringquery

  • statusstringquery

    One of pending sending success failed skipped

  • eventIdstring (uuid)query

Responses

200OK
  • dataWebhookDelivery[]required

  • idstring (uuid)required

  • endpointIdstring (uuid)required

  • eventIdstring (uuid)required

  • eventTypestringrequired

  • attemptintegerrequired

  • triggerstringrequired

    One of auto manual test

  • statusstringrequired

    One of pending sending success failed skipped

  • responseStatusinteger | nullrequired

  • responseExcerptstring | nullrequired

  • durationMsinteger | nullrequired

  • nextAttemptAtstring (date-time) | nullrequired

  • createdAtstring (date-time)required

  • metaPageMetarequired

  • next_cursorstring | nullrequired

  • per_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).

Request
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-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required 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

  • idstring (uuid)pathrequired

  • deliveryIdstring (uuid)pathrequired

Request body

Content types application/json

Responses

202Accepted
  • dataWebhookDeliveryrequired

  • idstring (uuid)required

  • endpointIdstring (uuid)required

  • eventIdstring (uuid)required

  • eventTypestringrequired

  • attemptintegerrequired

  • triggerstringrequired

    One of auto manual test

  • statusstringrequired

    One of pending sending success failed skipped

  • responseStatusinteger | nullrequired

  • responseExcerptstring | nullrequired

  • durationMsinteger | nullrequired

  • nextAttemptAtstring (date-time) | nullrequired

  • createdAtstring (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.

Request
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-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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-Keystringheader

    Only 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-Withstringheader

    Required 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

  • idstring (uuid)pathrequired

Request body

  • overlapHoursinteger

Responses

200OK
  • dataIssuedWebhookEndpointrequired

  • idstring (uuid)required

  • urlstringrequired

  • descriptionstring | nullrequired

  • eventsstring[]required

  • brandIds(string (uuid))[]required

  • accountIds(string (uuid))[]required

  • livemodebooleanrequired

  • statusstringrequired

    One of active failing disabled

  • consecutiveFailuresintegerrequired

  • failingSincestring (date-time) | nullrequired

  • apiVersionstringrequired

  • lastDeliveryobject | nullrequired

    The newest delivery to this endpoint, or null when it has none

  • statusstringrequired

    One of pending sending success failed skipped

  • atstring (date-time)required

  • createdAtstring (date-time)required

  • secretstringrequired

    The 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
Request
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-Versionstringheader

    The 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-01

  • X-Workspace-Idstring (uuid)header

    The 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-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required 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

  • idstring (uuid)pathrequired

Request body

Content types application/json

Responses

201Created
  • dataWebhookDeliveryrequired

  • idstring (uuid)required

  • endpointIdstring (uuid)required

  • eventIdstring (uuid)required

  • eventTypestringrequired

  • attemptintegerrequired

  • triggerstringrequired

    One of auto manual test

  • statusstringrequired

    One of pending sending success failed skipped

  • responseStatusinteger | nullrequired

  • responseExcerptstring | nullrequired

  • durationMsinteger | nullrequired

  • nextAttemptAtstring (date-time) | nullrequired

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409IdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable