# Webhook endpoints API

> Reference for the 10 public v1 operations of the Webhook endpoints API, generated from the OpenAPI spec.

Source: https://docs.nexafone.so/v1/api/webhook-endpoints/

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

## 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](/v1/api/schemas/#webhookendpointsoutputbody) |
| default | Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>" 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](/v1/api/schemas/#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](/v1/api/schemas/#webhooksecretoutputbody) |
| 401 | Unauthorized | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 409 | Conflict | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#webhookendpointbody) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#updatewebhookendpointinputbody)

| Field | Type | Required | 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](/v1/api/schemas/#webhookendpointbody) |
| 401 | Unauthorized | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#webhookdeliveriesoutputbody) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#problem) |
| 409 | Conflict | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#webhooksecretoutputbody) |
| 401 | Unauthorized | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#webhooktestoutputbody) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

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

## List the events an endpoint can subscribe to

`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](/v1/api/schemas/#webhookeventtypesoutputbody) |
| default | Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

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