Webhooks: events to your system

Signed messages after a call, an SMS, a campaign or on low balance, sent to your address.

A webhook is an address in your system (backend, CRM, n8n, Make, Zapier) that Brosbots sends a JSON POST to when something happens: a call ends, an SMS arrives, a campaign finishes its list. Every message is signed with your key, so you can check it came from us.

Setting up a webhook

Integrations → Custom tab → Notify on an event tile. The wizard has four steps:

1. Address - name, URL and signing key. The key is generated for you (whsec_…). Copy it straight away: after saving it is only shown masked. New key generates another one; replace it on your side too.
2. Events - which events to receive. call.completed is always on.
3. Agents - all of them or selected ones only. Events tied to an agent (calls, SMS, campaigns) of other agents do not reach this address. balance.low always arrives.
4. Test - sends an example event, signed like a real one. You see your server’s response code, the body sent and the signature header.

Edit the webhook later in the same wizard (Your integrations → Notifications). The same webhook also shows in the catalog as Post-call Webhook.

Webhooks are available from the Start plan.

Message format

Every event has the same envelope:

{
  "event": "call.completed",
  "sent_at": "2026-10-13T10:15:00+00:00",
  "data": { "...": "..." }
}

Headers:

Header	Value
Content-Type	application/json
X-Brosbots-Signature	sha256=<hex>: HMAC-SHA256 of the raw request body, keyed with your signing key

The wizard’s example has "test": true in data, so it is easy to filter out.

Events

Event	When	Main data fields
call.completed	after every call (always on)	workflow_run_id, workflow_id, workflow_name, duration_seconds, initial_context, gathered_context, recording_download_url, transcript_download_url
call.started	a call starts	workflow_run_id, workflow_id, direction, phone_number, channel, campaign_id, started_at
sms.received	an incoming SMS	sms_id, from_number, to_number, text, workflow_id, workflow_run_id, received_at
campaign.completed	a campaign has called every contact	the campaign summary and rows (each contact’s result)
balance.low	the balance reaches the warning threshold or drops below zero	balance, in_debt, minutes_left
lead.dropped	a lead the agent did not call: no credit for an hour, busy channels, a full queue, a lead limit, a dialling error (The Leads list)	lead_id, workflow_id, workflow_name, source, phone_number, name, status, reason, attempts, created_at

Full examples and field descriptions: Post-call webhook payload.

Verifying the signature

Compute HMAC-SHA256 over the raw request body (the bytes as received, before parsing the JSON) and compare it with the header in constant time. Re-serialising the JSON can reorder keys or change whitespace, and then the signature will not match.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.BROSBOTS_WEBHOOK_SECRET;

app.post("/webhooks/brosbots", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Brosbots-Signature") || "";
  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const { event, data } = JSON.parse(req.body.toString("utf8"));
  // ... handle the event
  res.status(204).end();
});

Make, Zapier and n8n usually do not check the signature: the webhook address is a secret in itself there. The key still helps if the address ever leaks.

Delivery and retries

• Answer with a 2xx within 15 seconds. The response body does not matter.
• On a connection error, a timeout, or 408, 425, 429, 5xx, we retry twice more (after 1 and after 5 seconds). Other 4xx codes count as a rejection and are not retried.
• Every attempt is listed under Recent deliveries below the integrations catalog, with the response code and the error.
• In rare cases the same event can arrive twice. Use event with data.workflow_run_id (or data.sms_id, data.campaign_id) to spot a repeat.

Security

• The address must be public: private-network addresses and localhost are blocked.
• The signing key is stored encrypted and is never returned in full by the API.
• The recording and transcript links in call.completed work without signing in. Treat them as personal data.