Webhooks

Push page and metadata activity to external systems

Outbound webhooks push page activity to external systems — CI, data warehouses, Slack bridges, custom apps — instead of making them poll.

Events

Event	Fires when
page.created	A page’s first revision is written (any door: HTTP, MCP, import)
page.updated	A new revision of an existing page is written
page.deleted	A page is deleted (admin or personal deletion)
page.metadata.updated	A metadata patch lands (payload lists changedKeys)

Personal-space activity never emits webhooks. A subscription can cover all shared spaces or be filtered to one space.

Delivery contract

Deliveries are POSTs with a JSON body:

{
  "id": "5f2c9d5e-…",
  "event": "page.metadata.updated",
  "occurredAt": "2026-07-19T08:12:45.120Z",
  "actor": { "id": "agent-key-id", "kind": "agent" },
  "page": { "path": "deals/acme", "space": "deals", "title": "Acme Corp", "version": 4 },
  "changedKeys": ["stage", "sources"]
}

Headers: X-Coco-Event, X-Coco-Delivery, X-Coco-Webhook, and X-Coco-Signature — an HMAC-SHA256 of the raw body with the webhook’s signing secret, formatted sha256=<hex>.

Verifying a signature

const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

Non-2xx responses and network failures retry with backoff (3 retries by default). Every attempt’s outcome lands in the delivery log (GET /admin/webhooks/:id/deliveries, or the Deliveries panel in the admin UI).

Management (org admin)

• GET/POST /admin/webhooks — list / create ({url, events, spaceSlug?, description?}; the signing secret is returned once on create)
• PATCH /admin/webhooks/:id — update URL, events, space filter, enable/disable
• POST /admin/webhooks/:id/rotate-secret — new secret, returned once
• POST /admin/webhooks/:id/test — send a webhook.test delivery and report the outcome
• DELETE /admin/webhooks/:id

Security posture

Webhook signing secrets are always stored encrypted. Webhooks require COCO_SETTINGS_ENCRYPTION_KEY on the API runtime (create/rotate return a clear 503 without it).

• Endpoints must be https; plain http requires the deployment to opt in with COCO_WEBHOOKS_ALLOW_HTTP=1 (payloads then transit unencrypted).
• SSRF guard: private, loopback, link-local, CGNAT, and reserved addresses (IPv4 and IPv6, including v4-mapped forms) are rejected — literals at create time, and again at delivery time after DNS resolution, so a hostname pointing at an internal address is blocked too (recorded in the delivery log, no retries). A small time-of-check/time-of-use window inherent to DNS remains; deployments with strict requirements should add egress filtering. COCO_WEBHOOKS_ALLOW_PRIVATE_URLS=1 disables the guard for intentionally internal deployments.