title: "Webhooks API" description: "Manage outgoing webhook endpoints and understand the payloads BoxWatch sends to your URLs." last_updated: "2026-05-24"

Webhooks API

Webhook endpoints are URLs you register so BoxWatch can POST to them when alerts fire. The API manages the channel definitions; deliveries flow outbound from BoxWatch. Conceptual docs: Webhook alerts.

All routes below require a bearer token.

Outgoing payload format

When an alert triggers, BoxWatch POSTs the following JSON to every enabled webhook whose alert_types matches (or is unset, meaning all types):

{
  "event": "alert.triggered",
  "timestamp": "2026-05-24T18:42:11Z",
  "alert": {
    "type": "cpu_high",
    "message": "CPU usage at 92% (threshold: 80%)"
  },
  "server": {
    "id": 12,
    "hostname": "web-01.prod",
    "ip": "10.0.1.5",
    "group": "Production"
  },
  "account": { "email": "[email protected]" }
}

Delivery headers:

Content-Type: application/json
User-Agent: BoxWatch-Webhook/1.0
Any custom headers you defined on the webhook (e.g. Authorization: Bearer ...).

Delivery timeout is 10 seconds. There is no retry — return a 2xx response within the window or the delivery is lost. Successful deliveries update last_triggered on the webhook row.

Possible alert.type values include cpu_high, memory_high, disk_high, server_offline, plus cron, process, and uptime alert types — match against types you've subscribed to via alert_types.

List webhooks

GET/webhooks

Auth: bearer

Returns all webhook endpoints on your account. Custom headers are not returned (they may contain secrets).

Response — 200 OK

{
  "webhooks": [
    {
      "id": 5,
      "name": "Slack #ops",
      "url": "https://hooks.slack.com/services/...",
      "alert_types": ["cpu_high", "server_offline"],
      "enabled": 1,
      "last_triggered": "2026-05-23T22:14:00Z",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ],
  "timestamp": "2026-05-24T18:42:11Z"
}

Create webhook

POST/webhooks

Auth: bearer

Request body

Field	Type	Required	Notes
`name`	string	yes	Display name. Trimmed.
`url`	string	yes	Target URL. Trimmed.
`headers`	object	no	Custom headers sent on every delivery (e.g. `{ "X-Token": "..." }`).
`alert_types`	string[]	no	Whitelist of alert types to deliver. Omit to receive every type.
`enabled`	boolean	no	Default `true`.

{
  "name": "Slack #ops",
  "url": "https://hooks.slack.com/services/T0/B0/abc",
  "headers": { "X-Webhook-Token": "shared-secret" },
  "alert_types": ["cpu_high", "memory_high", "server_offline"]
}

Response — 201 Created

{
  "webhook": {
    "id": 5,
    "name": "Slack #ops",
    "url": "https://hooks.slack.com/services/T0/B0/abc",
    "alert_types": ["cpu_high", "memory_high", "server_offline"],
    "enabled": true,
    "created_at": "2026-05-24T18:42:11Z"
  },
  "timestamp": "2026-05-24T18:42:11Z"
}

Errors

400 — Name is required or URL is required.

Update webhook

PUT/webhooks/:id

Auth: bearer

Send any subset of name, url, headers, alert_types, enabled. Provided fields overwrite their stored values (headers and alert_types are full replacements, not merges).

Response — 200 OK

{ "message": "Webhook updated", "timestamp": "2026-05-24T18:42:11Z" }

Errors

400 — No fields to update.
404 — Webhook not found.

Delete webhook

DELETE/webhooks/:id

Auth: bearer

Response — 200 OK

{ "message": "Webhook deleted", "timestamp": "2026-05-24T18:42:11Z" }

Errors

404 — Webhook not found.

Test webhook

POST/webhooks/:id/test

Auth: bearer

Sends a synthetic alert.test payload to the webhook URL using its stored custom headers. Use this from a script to confirm connectivity after rotating secrets.

Test payload

{
  "event": "alert.test",
  "timestamp": "2026-05-24T18:42:11Z",
  "alert": {
    "type": "cpu_high",
    "message": "TEST: CPU usage at 85% (threshold: 80%)"
  },
  "server": {
    "id": 0,
    "hostname": "test-server",
    "ip": "127.0.0.1",
    "group": "Test Group"
  },
  "account": { "email": "[email protected]" }
}

Response — 200 OK

{
  "success": true,
  "status_code": 200,
  "message": "Test webhook sent successfully",
  "timestamp": "2026-05-24T18:42:11Z"
}

success is true when the target returned a 2xx, otherwise false. On connection errors status_code is null and message describes the failure (e.g. "Webhook timed out (10s)").

Errors

404 — Webhook not found.