Alerts and webhooks

Set up an alert#

Set it up from your agent#

Each event has its own register_webhook_<event> tool, kept off your client's tool list: find it with find_tool, then run it with call_tool.

{
  "name": "register_webhook_chat_no_answer",
  "arguments": {
    "workspace_id": "acme/docs",
    "url": "https://hooks.example.com/docsbook",
    "secret": "at-least-16-characters-you-keep"
  }
}

The reply includes the webhook's secret, generated when you pass none. A Slack, Discord or Anthropic URL is recognised by its host and formatted for that app; any other URL gets the signed envelope.

Event catalog#

Sixteen events fire today. Each arrives named in underscore form, as below, in the X-Docsbook-Event header and the envelope's event field; the panel shows the same names with dots, as in chat.no_answer.

Plans appear as free, pro and business, the stored name of Enterprise.

What a delivery looks like#

A Custom webhook receives a POST with these headers:

POST /docsbook HTTP/1.1
Content-Type: application/json
User-Agent: Docsbook-Webhook/1.0
X-Docsbook-Event: chat_no_answer
X-Docsbook-Channel: api
X-Docsbook-Signature-256: sha256=<hex digest>

The body is the event envelope; data holds the catalog fields plus schema_version, which is 1.

{
  "event": "chat_no_answer",
  "workspace_id": 42,
  "timestamp": "2026-09-24T09:30:12.000Z",
  "data": {
    "schema_version": 1,
    "session_id": "<session id>",
    "question": "How do I rotate an API key?",
    "language": "en"
  }
}

• Chat apps and PagerDuty — Slack, Discord, Microsoft Teams and PagerDuty get a message shaped for that app instead.
• Email — the inbox gets a formatted email, unsigned.
• Claude — the routine gets the envelope plus a text prompt describing the event.
• Test pings — carry "test": true and a short message in data.

Verify the signature#

X-Docsbook-Signature-256 is sha256= followed by the hex HMAC-SHA256 of the exact request body, keyed with the webhook's signing secret. Compute it over the raw bytes, before parsing the JSON, and compare in constant time.

import crypto from "node:crypto"
 
export function isFromDocsbook(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

import hashlib
import hmac
 
def is_from_docsbook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Reject any request whose signature does not match: it did not come from Docsbook, or it was changed on the way.

Retries, tests and replays#

A delivery succeeds when your endpoint answers 2xx within 15 seconds.

• Retried — deliveries go out from a worker that runs every 5 minutes; a failed attempt is retried on the next run, up to 3 attempts in all, and then the delivery is marked failed.
• Recorded — a delivery keeps its last attempt's response code and the first 2,000 characters of the response body.
• Tested — test_webhook sends a test ping right away, outside the 5-minute cycle.
• Replayed — Replay on a delivery in Activity ▸ All events, or replay_webhook_delivery, sends the same payload again at once.
• Listed and removed — list_webhooks and list_webhook_deliveries show endpoints and attempts; Disconnect on the integration, or unregister_webhook, removes an endpoint.

See every event#

Activity ▸ All events lists everything the project produced, whether or not an alert was watching. Open a row for its Payload and each Delivery with its Replay button; an event nothing forwarded offers Wake an agent on events like this.

Next steps#