Real-time webhooks

Events

Add an endpoint under Developers → Webhooks and subscribe to any of these events.

Payload & signature

Each delivery is a JSON POST signed with HMAC-SHA256 over the raw body, using your endpoint's secret, in the X-BotForge-Signature header.

{
  "event": "order.paid",
  "workspaceId": "ws_...",
  "data": { "id": "ord_...", "number": 1042, "status": "paid", "total_cents": 4999, "currency": "usd" },
  "timestamp": "2026-07-06T10:15:00.000Z"
}

Verification

Always verify the signature before trusting a payload — never process an unverified body.

import crypto from "crypto";

function isValidSignature(rawBody: string, header: string, secret: string) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Use a timing-safe comparison (like crypto.timingSafeEqual) — a plain === check leaks timing information.

Retries

Non-2xx responses are retried up to 6 times with backoff. After the final failure, the endpoint owner is notified in-app.

Testing

Every endpoint's settings page has a Send test event button that fires a real, correctly-signed payload for any event type — no need to trigger the real action in your workspace. Delivery attempts, response codes and response bodies are all logged per-endpoint for debugging.

Examples

A full receiving handler example (Next.js route) is on the Examples page.