# Webhooks

> 9 endpoints: list webhook endpoints, create a webhook endpoint, retrieve a webhook endpoint, update a webhook endpoint, delete a webhook endpoint, roll a webhook secret, send a test event, list deliveries, retry a delivery.

- [List webhook endpoints](#list-webhook-endpoints): `GET /v1/webhook_endpoints`
- [Create a webhook endpoint](#create-a-webhook-endpoint): `POST /v1/webhook_endpoints`
- [Retrieve a webhook endpoint](#retrieve-a-webhook-endpoint): `GET /v1/webhook_endpoints/{endpoint_id}`
- [Update a webhook endpoint](#update-a-webhook-endpoint): `PATCH /v1/webhook_endpoints/{endpoint_id}`
- [Delete a webhook endpoint](#delete-a-webhook-endpoint): `DELETE /v1/webhook_endpoints/{endpoint_id}`
- [Roll a webhook secret](#roll-a-webhook-secret): `POST /v1/webhook_endpoints/{endpoint_id}/roll_secret`
- [Send a test event](#send-a-test-event): `POST /v1/webhook_endpoints/{endpoint_id}/test`
- [List deliveries](#list-deliveries): `GET /v1/webhook_endpoints/{endpoint_id}/deliveries`
- [Retry a delivery](#retry-a-delivery): `POST /v1/webhook_deliveries/{delivery_id}/retry`

### List webhook endpoints

`GET /v1/webhook_endpoints`

Lists the Workspace's webhook endpoints. Secrets are never listed.

Permission: `webhooks:read`

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |  |
| `data` | array of object | Yes |  |
| `data[].object` | `"webhook_endpoint"` | Yes |  |
| `data[].id` | string | Yes |  (up to 128 characters) |
| `data[].url` | string | Yes |  |
| `data[].description` | string or null | Yes |  |
| `data[].enabled_events` | array of string | Yes |  |
| `data[].project_ids` | array of string | Yes |  |
| `data[].api_version` | string | Yes |  |
| `data[].include_comment_content` | boolean | Yes |  |
| `data[].status` | `enabled`, `disabled` | Yes |  |
| `data[].disabled_reason` | string or null | Yes | manual, gone (the endpoint answered 410) or failing (five days of failures). |
| `data[].failing_since` | string or null | Yes |  |
| `data[].secret_last4` | string or null | Yes |  |
| `data[].created_at` | string | Yes | ISO 8601 date and time, UTC. |
| `has_more` | boolean | Yes |  |
| `next_cursor` | string or null | Yes |  |

```bash
curl https://api.nowscale.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"
```

### Create a webhook endpoint

`POST /v1/webhook_endpoints`

Adds an https endpoint (port 443) that receives the events you choose, signed with its own whsec_ secret. The secret is in this response only; reveal it later in Settings.

Permission: `webhooks:write` · Accepts `Idempotency-Key` · Answers `201`

#### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | Yes |  (up to 2048 characters) |
| `description` | string | No |  (up to 200 characters) |
| `enabled_events` | array of `*`, `post.created`, `post.published`, `post.partially_published`, `post.failed`, `post.deleted` | Yes | Event types to receive, or ["*"] for all. |
| `project_ids` | array of string | No | Only events from these Projects. Empty or absent: every Project. |
| `include_comment_content` | boolean | No | Comment events carry the comment's text and author name. |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_endpoint"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `url` | string | Yes |  |
| `description` | string or null | Yes |  |
| `enabled_events` | array of string | Yes |  |
| `project_ids` | array of string | Yes |  |
| `api_version` | string | Yes |  |
| `include_comment_content` | boolean | Yes |  |
| `status` | `enabled`, `disabled` | Yes |  |
| `disabled_reason` | string or null | Yes | manual, gone (the endpoint answered 410) or failing (five days of failures). |
| `failing_since` | string or null | Yes |  |
| `secret_last4` | string or null | Yes |  |
| `created_at` | string | Yes | ISO 8601 date and time, UTC. |
| `secret` | string | Yes | The signing secret, shown once. |

```bash
curl -X POST https://api.nowscale.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'
```

### Retrieve a webhook endpoint

`GET /v1/webhook_endpoints/{endpoint_id}`

Returns one endpoint, with the last four characters of its secret.

Permission: `webhooks:read`

#### Path parameters

| Name | Description |
| --- | --- |
| `endpoint_id` | The endpoint's id. |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_endpoint"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `url` | string | Yes |  |
| `description` | string or null | Yes |  |
| `enabled_events` | array of string | Yes |  |
| `project_ids` | array of string | Yes |  |
| `api_version` | string | Yes |  |
| `include_comment_content` | boolean | Yes |  |
| `status` | `enabled`, `disabled` | Yes |  |
| `disabled_reason` | string or null | Yes | manual, gone (the endpoint answered 410) or failing (five days of failures). |
| `failing_since` | string or null | Yes |  |
| `secret_last4` | string or null | Yes |  |
| `created_at` | string | Yes | ISO 8601 date and time, UTC. |

```bash
curl https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"
```

### Update a webhook endpoint

`PATCH /v1/webhook_endpoints/{endpoint_id}`

Changes the URL, events, Projects or description, or turns the endpoint off and on. Turning it on clears a failing streak.

Permission: `webhooks:write`

#### Path parameters

| Name | Description |
| --- | --- |
| `endpoint_id` | The endpoint's id. |

#### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | No |  (up to 2048 characters) |
| `description` | string or null | No |  |
| `enabled_events` | array of `*`, `post.created`, `post.published`, `post.partially_published`, `post.failed`, `post.deleted` | No | Event types to receive, or ["*"] for all. |
| `project_ids` | array of string | No |  |
| `include_comment_content` | boolean | No |  |
| `enabled` | boolean | No |  |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_endpoint"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `url` | string | Yes |  |
| `description` | string or null | Yes |  |
| `enabled_events` | array of string | Yes |  |
| `project_ids` | array of string | Yes |  |
| `api_version` | string | Yes |  |
| `include_comment_content` | boolean | Yes |  |
| `status` | `enabled`, `disabled` | Yes |  |
| `disabled_reason` | string or null | Yes | manual, gone (the endpoint answered 410) or failing (five days of failures). |
| `failing_since` | string or null | Yes |  |
| `secret_last4` | string or null | Yes |  |
| `created_at` | string | Yes | ISO 8601 date and time, UTC. |

```bash
curl -X PATCH https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

### Delete a webhook endpoint

`DELETE /v1/webhook_endpoints/{endpoint_id}`

Deletes the endpoint and the deliveries still waiting for it.

Permission: `webhooks:write`

#### Path parameters

| Name | Description |
| --- | --- |
| `endpoint_id` | The endpoint's id. |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_endpoint"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `deleted` | `true` | Yes |  |

```bash
curl -X DELETE https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"
```

### Roll a webhook secret

`POST /v1/webhook_endpoints/{endpoint_id}/roll_secret`

Creates a new signing secret. The old one keeps signing alongside it for 24 hours (two signatures per delivery) unless expire_now is true.

Permission: `webhooks:write` · Accepts `Idempotency-Key`

#### Path parameters

| Name | Description |
| --- | --- |
| `endpoint_id` | The endpoint's id. |

#### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expire_now` | boolean | No |  |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_endpoint"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `url` | string | Yes |  |
| `description` | string or null | Yes |  |
| `enabled_events` | array of string | Yes |  |
| `project_ids` | array of string | Yes |  |
| `api_version` | string | Yes |  |
| `include_comment_content` | boolean | Yes |  |
| `status` | `enabled`, `disabled` | Yes |  |
| `disabled_reason` | string or null | Yes | manual, gone (the endpoint answered 410) or failing (five days of failures). |
| `failing_since` | string or null | Yes |  |
| `secret_last4` | string or null | Yes |  |
| `created_at` | string | Yes | ISO 8601 date and time, UTC. |
| `secret` | string | Yes |  |

```bash
curl -X POST https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID/roll_secret \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'
```

### Send a test event

`POST /v1/webhook_endpoints/{endpoint_id}/test`

Queues a webhook_endpoint.test event to this endpoint, whatever its event filter.

Permission: `webhooks:write` · Answers `202`

#### Path parameters

| Name | Description |
| --- | --- |
| `endpoint_id` | The endpoint's id. |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_delivery"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `event_id` | string | Yes |  (up to 128 characters) |
| `status` | `"pending"` | Yes |  |

```bash
curl -X POST https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID/test \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

### List deliveries

`GET /v1/webhook_endpoints/{endpoint_id}/deliveries`

Lists an endpoint's deliveries of the last 30 days, newest first, with their attempts' outcome.

Permission: `webhooks:read`

#### Path parameters

| Name | Description |
| --- | --- |
| `endpoint_id` | The endpoint's id. |

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Items per page, 1 to 100. (1 to 100, default 25) |
| `cursor` | string | No | The next_cursor of the previous page. (up to 512 characters) |
| `status` | `pending`, `delivering`, `succeeded`, `failed` | No |  |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |  |
| `data` | array of object | Yes |  |
| `data[].object` | `"webhook_delivery"` | Yes |  |
| `data[].id` | string | Yes |  (up to 128 characters) |
| `data[].endpoint_id` | string | Yes |  (up to 128 characters) |
| `data[].event_id` | string | Yes |  (up to 128 characters) |
| `data[].event_type` | string | Yes |  |
| `data[].status` | `pending`, `delivering`, `succeeded`, `failed` | Yes |  |
| `data[].attempts` | integer | Yes |  (-9007199254740991 to 9007199254740991) |
| `data[].next_attempt_at` | string or null | Yes |  |
| `data[].last_status_code` | integer or null | Yes |  |
| `data[].last_error` | string or null | Yes |  |
| `data[].delivered_at` | string or null | Yes |  |
| `data[].created_at` | string | Yes | ISO 8601 date and time, UTC. |
| `has_more` | boolean | Yes |  |
| `next_cursor` | string or null | Yes |  |

```bash
curl https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID/deliveries \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"
```

### Retry a delivery

`POST /v1/webhook_deliveries/{delivery_id}/retry`

Sends a delivery again now, keeping its webhook-id, whatever its status.

Permission: `webhooks:write` · Answers `202`

#### Path parameters

| Name | Description |
| --- | --- |
| `delivery_id` | The delivery's id. |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"webhook_delivery"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `endpoint_id` | string | Yes |  (up to 128 characters) |
| `event_id` | string | Yes |  (up to 128 characters) |
| `event_type` | string | Yes |  |
| `status` | `pending`, `delivering`, `succeeded`, `failed` | Yes |  |
| `attempts` | integer | Yes |  (-9007199254740991 to 9007199254740991) |
| `next_attempt_at` | string or null | Yes |  |
| `last_status_code` | integer or null | Yes |  |
| `last_error` | string or null | Yes |  |
| `delivered_at` | string or null | Yes |  |
| `created_at` | string | Yes | ISO 8601 date and time, UTC. |

```bash
curl -X POST https://api.nowscale.com/v1/webhook_deliveries/DELIVERY_ID/retry \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```