Skip to the content

You are reading the reference as of 2026-10-09. The API serves the latest version. Read this page for the latest version

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

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). A webhook without one receives nothing
secret string The key of the signature. Only in the answer of POST /api/webhooks
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.

POST /api/webhooks
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": []
}'
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks",
    data=json.dumps({"url": "https://erp.example.com/hooks/hts-pilot", "events": []}).encode(),
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks", {
  method: "POST",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "url": "https://erp.example.com/hooks/hts-pilot",
    "events": []
  }),
});
console.log(await response.json());
Response 200
{
  "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.

GET /api/webhooks
curl "https://htspilot.com/api/webhooks" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
[
  {
    "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"
  }
]

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.

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.

PATCH /api/webhooks/{hook_id}
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
}'
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa",
    data=json.dumps({"active": False}).encode(),
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
    method="PATCH",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa", {
  method: "PATCH",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "active": false
  }),
});
console.log(await response.json());
Response 200
{
  "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"
}

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.

DELETE /api/webhooks/{hook_id}
curl -X DELETE "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="DELETE",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "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.

ok is true when your endpoint answered 2xx.

POST /api/webhooks/{hook_id}/test
curl -X POST "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/test" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/test",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/test", {
  method: "POST",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "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"
}

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.

GET /api/webhooks/{hook_id}/deliveries
curl "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/deliveries" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/deliveries",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks/10833e92a3304c0db9f235b06c76b1aa/deliveries", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
[
  {
    "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.

GET /api/webhooks/events
curl "https://htspilot.com/api/webhooks/events" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/webhooks/events",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/webhooks/events", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "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"
}