Documentation / Webhooks

Webhooks

Configure an endpoint under Settings → Webhooks and BotForge will POST a signed JSON payload for each subscribed event.

Event catalogue

Event	Description
bot.published	A new flow version was published
subscriber.created	A new subscriber joined a bot
subscriber.blocked	A subscriber blocked the bot
broadcast.completed	A broadcast finished sending
broadcast.failed	A broadcast failed to send
message.inbound	An inbound message was received

Verifying signatures

Every request includes an X-BotForge-Signature header: an HMAC-SHA256 hex digest of the raw request body, keyed with your endpoint secret.

const expected = crypto
  .createHmac("sha256", endpointSecret)
  .update(rawBody)
  .digest("hex");

if (expected !== req.headers["x-botforge-signature"]) {
  return res.status(401).end();
}

Retries and backoff

Deliveries that don't receive a 2xx within 5 seconds are retried with exponential backoff: 1m, 5m, 30m, 2h, then 12h, for up to 24 hours. After the final attempt fails, the endpoint is flagged and you'll be notified by email. Endpoints with a >50% failure rate over 1 hour are temporarily disabled.

Payload example

{
  "id": "evt_3n7f",
  "type": "broadcast.completed",
  "createdAt": "2024-05-02T14:03:11Z",
  "data": {
    "broadcastId": "bcast_7f1",
    "botId": "bot_9k2",
    "stats": { "total": 4210, "delivered": 4180, "blocked": 19, "failed": 11 }
  }
}