Webhooks

NookDocs can POST signed JSON payloads to any HTTPS endpoint when supported events fire on your project. Use it to ping Slack on deploy, file Linear tickets on negative feedback, or mirror published pages to a downstream system.

Available events

A subscription with an empty event list receives all supported events.

Payload envelope

Every delivery uses the same outer shape:

{
  "event": "deployment.completed",
  "timestamp": "2026-05-03T12:34:56.789Z",
  "project": {
    "id": "uuid",
    "subdomain": "your-project"
  },
  "data": { "...": "event-specific" }
}

Headers

Verifying the signature

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, signatureHeader: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader.replace(/^sha256=/, "");
  if (expected.length !== provided.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

Always compare the raw body — JSON re-serialization will change the bytes and break the signature.

Where to manage them

Project → Settings → Webhooks. Click Add webhook, paste your URL, optionally tick which events to subscribe to, and click Create. The signing secret is shown once in a one-time-reveal modal — store it on your receiver immediately. Each row supports Test (sends a synthetic deployment.completed event), Pause/Resume, and Delete.

Plan availability

Delivery + retry

• 10s timeout per attempt

• Telemetry on every row: last_status, last_attempted_at, last_succeeded_at, failure_count

• No automatic retry yet — your receiver should be idempotent and process events from the most recent delivery wins. Retry queue is on the roadmap.

Notes

• Failed deliveries don't stop deployment / feedback writes. Webhook delivery is best-effort.

• Receiver must respond 2xx to count as success.

• For Slack / Discord, point the URL at their incoming-webhook endpoint and write a small adapter — those services have their own JSON shapes.

import { createHmac, timingSafeEqual } from "node:crypto";

function isValidNookDocsSignature(
  rawBody: string,
  signatureHeader: string | undefined,
  secret: string,
): boolean {
  if (!signatureHeader) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader.replace(/^sha256=/, "");
  if (expected.length !== provided.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

switch (req.headers["x-nookdocs-event"]) {
  case "deployment.completed": /* read req.body.data.{commit_sha, pages_total, ...} */ break;
  case "deployment.failed":    /* req.body.data.{error} */ break;
  case "page.feedback.received": /* req.body.data.{path, rating, reason, comment} */ break;
  case "page.published":       /* req.body.data.{path, title} — reserved */ break;
}