Webhook endpoints API

View as Markdown llms.txt

Generated from api/openapi.public.yaml, the same spec the API serves. Try these operations in the API console; errors are Problem Details.

List the workspace’s webhook endpoints

GET /api/v1/workspaces/{workspaceId}/webhook-endpoints


Operation id	`listWebhookEndpoints`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)

Responses

Status	Description	Body
200	OK	`application/json`: WebhookEndpointsOutputBody
default	Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Register a webhook endpoint

POST /api/v1/workspaces/{workspaceId}/webhook-endpoints

Every delivery is a POST with the event as JSON and a Nexafon-Signature header: t=,v1=<hex HMAC-SHA256 of “.” keyed with the secret>. Reject a timestamp more than 5 minutes old. The secret is in this response only. A dashboard session needs a sign-in within the last 10 minutes; otherwise it answers 401 reauthentication_required. An SDK session is refused with 403 dashboard_sign_in_required.


Operation id	`createWebhookEndpoint`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)

Request body

application/json: CreateWebhookEndpointInputBody

Field	Type	Required	Description
`description`	string		(max length 200)
`events`	array of string	yes	Event types from GET /webhook-event-types (min 1 items, max 64 items)
`url`	string	yes	An https URL on the public internet (min length 8, max length 2048)

Responses

Status	Description	Body
201	Created	`application/json`: WebhookSecretOutputBody
401	Unauthorized	`application/problem+json`: Problem
409	Conflict	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["string"],"url":"string"}'

Get a webhook endpoint

GET /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}


Operation id	`getWebhookEndpoint`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)

Responses

Status	Description	Body
200	OK	`application/json`: WebhookEndpointBody
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Change a webhook endpoint, or turn it off or back on

PATCH /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}

A dashboard session needs a sign-in within the last 10 minutes; otherwise it answers 401 reauthentication_required. An SDK session is refused with 403 dashboard_sign_in_required.


Operation id	`updateWebhookEndpoint`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)

Request body

application/json: UpdateWebhookEndpointInputBody

Field	Type	Description
`description`	string	(max length 200)
`events`	array of string or null	(min 1 items, max 64 items)
`status`	`"active"` \| `"disabled"`	active turns a disabled endpoint back on
`url`	string	(min length 8, max length 2048)

Responses

Status	Description	Body
200	OK	`application/json`: WebhookEndpointBody
401	Unauthorized	`application/problem+json`: Problem
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X PATCH "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a webhook endpoint and its delivery log

DELETE /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}


Operation id	`deleteWebhookEndpoint`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)

Responses

Status	Description	Body
204	No Content
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X DELETE "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

List every delivery attempt to an endpoint

GET /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/deliveries


Operation id	`listWebhookDeliveries`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)
`eventId`	query	string (uuid)		Only this event’s attempts
`status`	query	`"succeeded"` \| `"failed"`
`cursor`	query	string		The next value of the previous page
`limit`	query	integer (int64)

Responses

Status	Description	Body
200	OK	`application/json`: WebhookDeliveriesOutputBody
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/deliveries" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Send an event to an endpoint again

POST /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/events/{eventId}/replay

The event keeps its id. It is retried on the usual schedule; the delivery log shows every attempt.


Operation id	`replayWebhookEndpointEvent`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)
`eventId`	path	string	yes	Event id (UUID) from the delivery log

Responses

Status	Description	Body
202	Accepted
404	Not Found	`application/problem+json`: Problem
409	Conflict	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/events/{eventId}/replay" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Replace a webhook endpoint’s signing secret

POST /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/rotate-secret

Until previousSecretExpiresAt the Nexafon-Signature header carries a v1 signature for each secret, so the receiver can switch over without missing an event. The new secret is in this response only. A dashboard session needs a sign-in within the last 10 minutes; otherwise it answers 401 reauthentication_required. An SDK session is refused with 403 dashboard_sign_in_required.


Operation id	`rotateWebhookEndpointSecret`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)
`keepPreviousHours`	query	integer (int64)		How long deliveries are also signed with the replaced secret

Responses

Status	Description	Body
200	OK	`application/json`: WebhookSecretOutputBody
401	Unauthorized	`application/problem+json`: Problem
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/rotate-secret" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Send a webhook.test event to an endpoint

POST /api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/test

Works on a disabled endpoint too. It is tried once; the delivery log shows the result.


Operation id	`sendWebhookTest`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`endpointId`	path	string	yes	Webhook endpoint id (UUID)

Responses

Status	Description	Body
202	Accepted	`application/json`: WebhookTestOutputBody
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-endpoints/{endpointId}/test" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

GET /api/v1/workspaces/{workspaceId}/webhook-event-types


Operation id	`listWebhookEventTypes`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`developers:manage`
Plan feature	`workspace.core`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)

Responses

Status	Description	Body
200	OK	`application/json`: WebhookEventTypesOutputBody
default	Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/webhook-event-types" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Webhook endpoints API

List the workspace’s webhook endpoints

Parameters

Responses

Example

Register a webhook endpoint

Parameters

Request body

Responses

Example

Get a webhook endpoint

Parameters

Responses

Example

Change a webhook endpoint, or turn it off or back on

Parameters

Request body

Responses

Example

Delete a webhook endpoint and its delivery log

Parameters

Responses

Example

List every delivery attempt to an endpoint

Parameters

Responses

Example

Send an event to an endpoint again

Parameters

Responses

Example

Replace a webhook endpoint’s signing secret

Parameters

Responses

Example

Send a webhook.test event to an endpoint

Parameters

Responses

Example

List the events an endpoint can subscribe to

Parameters

Responses

Example