> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

> This page describes the API as of 2026-10-09. The service runs the latest version: https://docs.htspilot.com/webhook-endpoints.md

# Webhook endpoints

> Register, change, test and delete webhooks through the API, and read the deliveries of a webhook.

These operations manage the webhooks themselves. What a webhook sends, how to verify it and how it retries is in
[Webhooks](/v/2026-10-09/webhooks.md). All of them but `GET /api/webhooks/events` need the `admin` role; creating, changing and
testing also need the plan feature `feature.webhooks`. `GET /api/webhooks/events` is open to every key, whatever
its role.

While the service has workspaces switched on, these operations see and change the webhooks of the key's own
workspace only, and a webhook of another workspace answers `404`. The role is the key's role in that workspace,
the plan is the workspace's, and `POST /api/webhooks` and a `PATCH` that sends `url` are answered `403` with the
code `session_required`: a person signed in to the application does those
([Authentication](/v/2026-10-09/authentication.md#workspaces)).

## The webhook object

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | The id of the webhook |
| `url` | string | Where deliveries are sent |
| `events` | array | The event names it receives. Empty means every event |
| `active` | boolean | A paused webhook receives nothing |
| `created_at` | string | ISO 8601, UTC |
| `last_status` | integer or null | The HTTP status your endpoint gave to the latest delivery |
| `last_error` | string or null | Why the latest delivery failed |
| `last_delivery_at` | string or null | When the latest delivery ended |
| `organisation_id` | string or null | The workspace the webhook belongs to: it receives the events of that workspace only ([Webhooks](/v/2026-10-09/webhooks.md#which-events-a-webhook-receives)). A webhook without one receives nothing |
| `secret` | string | The key of the signature. Only in the answer of `POST /api/webhooks` |

## The delivery object

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | integer | The delivery id, as sent in `X-HTS-Delivery` |
| `event` | string | The event name |
| `status_code` | integer or null | The HTTP status of the last attempt. `null` when no answer was received |
| `error` | string or null | Why it failed: the start of your endpoint's answer, or a general reason |
| `attempts` | integer | How many attempts were made |
| `created_at` | string | ISO 8601, UTC |

## Register a webhook

`POST /api/webhooks`

**Changes data in your account when executed.** The answer contains `secret`, the key of the `X-HTS-Signature` header. It is shown only here. Leave `events` empty to receive every event. The URL must be `https` and resolve to a public address. The webhook belongs to the workspace it is created in. With an API key: `403` `session_required` while workspaces are switched on; a person signed in to the application registers the webhook then. Needs the admin role; while workspaces are switched on, the workspace admin role, in the key's own workspace.

**Request body** (`application/json`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | Yes | Up to 2083 characters |
| `events` | string[] | No | Empty = all events |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl -X POST "https://htspilot.com/api/webhooks" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.example.com/hooks/hts-pilot",
  "events": []
}'
```

**Example response** `200`

```json
{
  "id": "10833e92a3304c0db9f235b06c76b1aa",
  "url": "https://erp.example.com/hooks/hts-pilot",
  "events": [],
  "active": true,
  "created_at": "2026-10-09T03:17:00.352650+00:00",
  "last_status": null,
  "last_error": null,
  "last_delivery_at": null,
  "organisation_id": "ddc09ece227d466bbcedf0ab04fc8e29",
  "secret": "0123456789abcdef0123456789abcdef0123456789abcdef"
}
```

## List webhooks

`GET /api/webhooks`

Needs the admin role; while workspaces are switched on, the workspace admin role, in the key's own workspace.

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/webhooks" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
[
  {
    "id": "10833e92a3304c0db9f235b06c76b1aa",
    "url": "https://erp.example.com/hooks/hts-pilot",
    "events": [],
    "active": true,
    "created_at": "2026-10-09T03:17:00.352650",
    "last_status": 200,
    "last_error": null,
    "last_delivery_at": "2026-10-09T03:17:02.317325",
    "organisation_id": "ddc09ece227d466bbcedf0ab04fc8e29"
  }
]
```

## Change or pause a webhook

`PATCH /api/webhooks/{hook_id}`

**Changes data in your account when executed.** Send only what changes. With an API key, a request that sends `url`: `403` `session_required` while workspaces are switched on; `active` and `events` can still be changed with a key. Needs the admin role; while workspaces are switched on, the workspace admin role, in the key's own workspace.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `hook_id` | string | - |

**Request body** (`application/json`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string or null | No | Up to 2083 characters |
| `events` | string[] or null | No | - |
| `active` | boolean or null | No | - |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl -X PATCH "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
```

**Example response** `200`

```json
{
  "id": "10833e92a3304c0db9f235b06c76b1aa",
  "url": "https://erp.example.com/hooks/hts-pilot",
  "events": [],
  "active": false,
  "created_at": "2026-10-09T03:17:00.352650",
  "last_status": 200,
  "last_error": null,
  "last_delivery_at": "2026-10-09T03:17:02.317325",
  "organisation_id": "ddc09ece227d466bbcedf0ab04fc8e29"
}
```

Send only what changes. A new `url` is checked like a new webhook. While workspaces are switched on, a request
made with a key that sends `url` is answered `403` with `session_required`; `active` and `events` can still be
changed with a key. The secret cannot be changed here; to rotate it,
delete the webhook and register it again.

## Delete a webhook

`DELETE /api/webhooks/{hook_id}`

**Deletes for real when executed, and cannot be undone.** Needs the admin role; while workspaces are switched on, the workspace admin role, in the key's own workspace.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `hook_id` | string | - |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl -X DELETE "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
{
  "ok": true
}
```

## Send a test event

`POST /api/webhooks/{hook_id}/test`

**Changes data in your account when executed.** Sends the event `ping` now, with the same body shape, headers and signature as a real event, and answers with the result. Needs the admin role; while workspaces are switched on, the workspace admin role, in the key's own workspace.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `hook_id` | string | - |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl -X POST "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/test" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
{
  "ok": true,
  "id": "10833e92a3304c0db9f235b06c76b1aa",
  "url": "https://erp.example.com/hooks/hts-pilot",
  "events": [],
  "active": true,
  "created_at": "2026-10-09T03:17:00.352650",
  "last_status": 200,
  "last_error": null,
  "last_delivery_at": "2026-10-09T03:17:02.317325",
  "organisation_id": "ddc09ece227d466bbcedf0ab04fc8e29"
}
```

`ok` is `true` when your endpoint answered `2xx`.

## List deliveries

`GET /api/webhooks/{hook_id}/deliveries`

Needs the admin role; while workspaces are switched on, the workspace admin role, in the key's own workspace.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `hook_id` | string | - |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/deliveries" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
[
  {
    "id": 6,
    "event": "ping",
    "status_code": 200,
    "error": null,
    "attempts": 1,
    "created_at": "2026-10-09T03:17:02.312732"
  },
  {
    "id": 5,
    "event": "batch.completed",
    "status_code": 200,
    "error": null,
    "attempts": 1,
    "created_at": "2026-10-09T03:17:01.578717"
  }
]
```

## List event names

`GET /api/webhooks/events`

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, the plan of the account, or the workspace of the request does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/webhooks/events" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
{
  "lookup.completed": "A lookup finished",
  "lookup.decided": "A reviewer approved / overrode / rejected a code",
  "batch.completed": "A batch file finished processing",
  "tariff.changed": "A new tariff version and code changes were detected",
  "sku.alert": "A SKU is affected by a tariff change"
}
```
