वेबहुक

Setup

1. Open Integrations → Webhooks & API in your dashboard and click Add webhook.
2. Enter your endpoint URL. It must be https:// and resolve to a public address.
3. Pick the events to receive.
4. Copy the signing secret (whsec_…) from the dialog that opens. It is shown once. Lost it? Click Regenerate on the endpoint — the old secret stops working at once.
5. Click Test to send a test.ping event and confirm your receiver answers.

The number of endpoints depends on your plan (Free 2, Starter 10, Growth 30, Pro 100, Agency unlimited). Creating one past the limit returns 402 with code WEBHOOK_LIMIT.

Events

The request

One POST per event per endpoint, JSON body of event, data and timestamp:

POST https://your-server.example/beecastly
Content-Type: application/json
User-Agent: BeeCastly-Webhooks/1.0
X-BeeCastly-Event: message.received
X-BeeCastly-Signature: sha256=5d41402abc4b2a76b9719d911017c592…

{
  "event": "message.received",
  "data": {
    "messageId": "cmg8x2k1…",
    "conversationId": "cmg8x2j9…",
    "from": "12025551234",
    "text": "Hello!",
    "contactId": "cmg1k9…",
    "contactName": "John Doe",
    "contactPhone": "+12025551234",
    "receivedAt": "2026-10-05T12:00:00.000Z"
  },
  "timestamp": "2026-10-05T12:00:00.412Z"
}

Verifying the signature

// Node.js / Express
const crypto = require('crypto');

app.post('/beecastly', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.BEECASTLY_WEBHOOK_SECRET) // whsec_…
    .update(req.body) // the raw Buffer
    .digest('hex');
  const got = req.get('X-BeeCastly-Signature') || '';
  const ok = got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body);
  // …handle the event, idempotently (see Retries)
  res.sendStatus(200);
});