Webhooks

Set up

1. Open CRM integrations and choose Connect on the Webhook card. Webhooks are included in the Growth plan and above, and only people who can manage integrations can set them up.
2. Enter your endpoint. It must be https:// and reachable from the internet.
3. Set a signing secret of at least 16 characters, then store the same value on your server. CallBix never shows it again.
4. Pick the events you want, then save.
5. Press Send test event to check that your endpoint answers with a 2xx.

The card's switches also apply: with Log calls automatically off nothing is sent, and with Log missed calls off, missed calls are left out.

Events

A new call is sent about two minutes after it ends, so the agent's notes and the recording usually arrive in the same call.created. Changes made close together are combined. If you don't subscribe to call.created, the first event you get for a call is its first update.

Payload

Every event carries the whole current state of the call, not only what changed, so you can always overwrite your copy with what you receive.

{
  "event": "call.updated",
  "deliveryId": "8b0f6c1e-3a52-4c55-9d6a-0b7d3e2f9a41",
  "sentAt": "2026-10-02T06:15:31.204Z",
  "call": {
    "id": "66fc1f5e9b1d4a0012a3b4c5",
    "phoneNumber": "+91 98765 43210",
    "normalizedNumber": "+919876543210",
    "contactName": "Priya Sharma",
    "direction": "OUTGOING",
    "startedAt": "2026-10-02T06:09:12.000Z",
    "durationSec": 252,
    "disposition": "Interested",
    "notes": "Wants a site visit on Saturday.",
    "followUpAt": "2026-10-04T04:30:00.000Z",
    "tags": [],
    "recordingUrl": "https://api.callbix.app/public/recordings/66fc1f5e…?exp=…&sig=…",
    "fields": {
      "budget": 7500000,
      "site_visit_booked": true,
      "product_interest": ["2 BHK", "3 BHK"]
    },
    "agent": {
      "id": "66f9a2b1c3d4e5f601234567",
      "name": "Ravi Kumar",
      "email": "ravi@acme.in",
      "phone": "+91 99887 76655"
    }
  },
  "contact": null
}

Field reference

Custom fields

To collect more than the outcome and notes, open Webhook → Fields & status and add fields. For each one you choose a label (what agents see after a call), a key, and a type. Agents fill them in on the phone or the web, and they arrive in call.fields under your keys.

Headers

Verifying signatures

Compute HMAC-SHA256 over the raw request body, exactly as received, using your signing secret. Hex-encode the result and compare it to X-CallBix-Signature with a constant-time comparison. Parsing and re-serialising the JSON first changes the bytes and breaks the check.

sentAt is inside the signed body, so checking it's recent (within five minutes, say) stops someone from replaying an old request.

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

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

// Verify against the raw bytes — not re-serialised JSON
app.post("/callbix", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-CallBix-Signature") ?? "";
  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).send("bad signature");

  const event = JSON.parse(req.body.toString("utf8"));
  const ageMs = Date.now() - Date.parse(event.sentAt);
  if (ageMs > 5 * 60_000) return res.status(400).send("too old");

  // Answer fast; do the real work in a queue
  queue.add(event);
  res.sendStatus(204);
});

<?php
$secret = getenv('CALLBIX_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, $secret);
$received = $_SERVER['HTTP_X_CALLBIX_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('bad signature');
}

$event = json_decode($raw, true);
if (time() - strtotime($event['sentAt']) > 300) {
    http_response_code(400);
    exit('too old');
}

// ... store or queue $event ...
http_response_code(204);

import hashlib, hmac, json, os, time
from datetime import datetime
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["CALLBIX_WEBHOOK_SECRET"].encode()

@app.post("/callbix")
def callbix():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-CallBix-Signature", "")):
        abort(401)

    event = json.loads(raw)
    sent = datetime.fromisoformat(event["sentAt"].replace("Z", "+00:00")).timestamp()
    if time.time() - sent > 300:
        abort(400)

    # ... store or queue the event ...
    return "", 204

Delivery & retries

• Any 2xx answer within 15 seconds counts as delivered. The response body is ignored.
• Timeouts, network errors, 5xx, 401, 408 and 429 are retried with growing gaps: about 2 minutes, then 4, 8, 16 and so on, capped at 6 hours, for up to 8 attempts.
• Any other 4xx (such as 400, 404 or 422) is treated as permanent and isn't retried.
• Calls that couldn't be delivered show as Failed on the call and on the Webhook card. After fixing your endpoint, press Retry failed to send them again.

Handling events well

• Upsert by call.id. The same event can arrive more than once (after a retry, for example), and every event holds the full call, so insert-or-update on call.id rather than appending.
• Ignore stale updates. Events are usually in order, but a retry can land after a newer event. Keep the sentAt you last applied for each call and skip anything older.
• Answer quickly. Store the event and reply 2xx; do slow work (CRM calls, emails) in the background.
• Copy the recording if you need it for good. recordingUrl expires, and recordings are removed after your plan's retention period.

Testing

Send test event on the Webhook card posts a signed ping with a sample call, including your custom field keys, and shows the status code your endpoint returned. While you build, a request inspector such as webhook.site or a local tunnel (ngrok, Cloudflare Tunnel) lets you see exactly what arrives.