Webhooks

Configure an HTTPS endpoint in the dashboard (webhook endpoints are dashboard-only, not MCP). Deliveries POST a JSON envelope and sign the raw body with HMAC-SHA256. Verify header X-Bootstrapware-Signature (hex digest) using your endpoint secret.

Webhooks carry operational identifiers only. They do not include host context, flags, or step copy. A failed delivery is retried once. Hosted cancel freezes writes immediately, so new events stop.

Events

  • onboard.flow_started (flowId, userId, workspaceKey, revision)
  • onboard.item_completed / onboard.item_skipped (flowId, stepKey, userId, workspaceKey, revision, scope)
  • onboard.flow_completed (flowId, userId, workspaceKey, revision, requirementsSatisfied)
  • onboard.flow_dismissed / onboard.flow_snoozed / onboard.flow_resumed (flowId, userId, workspaceKey)
  • onboard.progress_reset (flowId, userId, workspaceKey — personal generation only)

Envelope shape

{
  "event": "onboard.item_completed",
  "workspaceId": "ws_...",
  "productId": "onboard",
  "timestamp": "2026-09-05T12:00:00.000Z",
  "data": { /* event-specific ids only */ }
}

Verify signature (Node)

Compare the header to HMAC-SHA256 of the exact raw request body (hex). Use a timing-safe compare:

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

function verifyBootstrapwareSignature(
  rawBody: string,
  header: string | null,
  secret: string,
) {
  if (!header) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(header, "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Parse JSON only after verification. Do not re-serialize the body before hashing. The signature is over the bytes that were POSTed.

BYO does not emit these

Hosted progress events emit Bootstrapware Onboard webhooks. BYO adapters keep progress on your backend and do not emit Bootstrapware onboard webhooks for your store. Wire onEvent on the widget (or your own API) if you need Slack or CRM side effects.

Narrative guide: Onboard webhooks.

Related: Webhooks guide · Sessions · API overview · Security