Click-to-Call Webhook Events

​

Events

​

Headers

​

Payload

{
  "event_id": "c4d79b8d-5b2d-8ff1-84b0-5943d59b21a0",
  "sequence": 2,
  "status_code": 200,
  "message": "Call completed.",
  "error": null,
  "event": "call.completed",
  "data": {
    "call_id": "7d004ba2-565f-4ee2-9aa2-19523d8db7ae",
    "reference_id": "crm-task-91823",
    "did": "917900000000",
    "agent_number": "919812345678",
    "customer_number": "919876543210",
    "call_type": "C2C",
    "duration": "92",
    "answer_duration": "66",
    "start_time": "2026-09-23T14:11:27.134Z",
    "answer_time": "2026-09-23T14:11:53.392Z",
    "end_time": "2026-09-23T14:12:59.921Z",
    "hangup_cause": "NORMAL_CLEARING",
    "metadata": { "lead_id": "L-991" }
  },
  "qcall": {
    "call_id": "7d004ba2-565f-4ee2-9aa2-19523d8db7ae",
    "reference_id": "crm-task-91823",
    "event_id": "c4d79b8d-5b2d-8ff1-84b0-5943d59b21a0",
    "delivered_at": "2026-09-23T14:13:00.410Z"
  }
}

​

Verifying the signature

signature = "v1=" + HMAC-SHA256(
    key     = your callback_secret, as raw UTF-8 bytes,
    message = x-qcall-timestamp + "." + raw_request_body
)

1. Use the secret exactly as you sent it. There is no decoding step — the HMAC key is the string’s own UTF-8 bytes.
2. Use the raw body bytes. Re-serialising parsed JSON changes whitespace and key order and breaks the signature. Capture the raw body before your JSON middleware touches it.

const crypto = require('node:crypto');

const SECRET = process.env.QCALL_WEBHOOK_SECRET; // the same string you sent

function verify(rawBody, headers) {
  const ts = Number(headers['x-qcall-timestamp']);
  // Reject stale or future timestamps to blunt replay attempts.
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const got = String(headers['x-qcall-signature'] || '').replace(/^v1=/, '');
  if (!/^[0-9a-f]{64}$/.test(got)) return false;

  const expected = crypto.createHmac('sha256', Buffer.from(SECRET, 'utf8'))
    .update(String(ts)).update('.').update(rawBody).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(got, 'hex'), Buffer.from(expected, 'hex'));
}

app.post('/webhooks/qcall',
  express.raw({ type: 'application/json' }),   // raw body, not express.json()
  (req, res) => {
    if (!verify(req.body, req.headers)) return res.sendStatus(401);

    const event = JSON.parse(req.body.toString('utf8'));
    if (seen.has(req.headers['x-qcall-event-id'])) return res.sendStatus(200);

    res.sendStatus(200);   // acknowledge first — you have 5 seconds
    enqueue(event);        // then do the work
  });

import hmac, hashlib, os, time
from flask import request, abort

SECRET = os.environ["QCALL_WEBHOOK_SECRET"].encode()

def verify(raw_body: bytes, headers) -> bool:
    ts = headers.get("x-qcall-timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    got = headers.get("x-qcall-signature", "").removeprefix("v1=")
    if len(got) != 64:
        return False
    expected = hmac.new(
        SECRET, ts.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(got, expected)

@app.post("/webhooks/qcall")
def qcall_webhook():
    if not verify(request.get_data(), request.headers):
        abort(401)

    event_id = request.headers["x-qcall-event-id"]
    if not already_seen(event_id):
        enqueue(request.get_json())   # process asynchronously

    return "", 200

​

Receiver requirements

• Respond 2xx within 5 seconds. Acknowledge first, process asynchronously — a slow handler is a failed delivery.
• Deduplicate on x-qcall-event-id; the same event can arrive more than once.
• Make processing idempotent.
• Use a constant-time comparison (crypto.timingSafeEqual, hmac.compare_digest).
• Check x-qcall-timestamp against your clock with a tolerance of a few minutes.
• Serve HTTPS on a publicly resolvable host. Private, loopback, link-local and CGNAT addresses are rejected, and the destination is re-validated — with the socket pinned to the addresses that passed — before every delivery, so DNS rebinding can’t redirect a delivery after the fact.

​

Retries

• Up to 6 attempts per event, at least two minutes apart.
• Abandoned once the event is 24 hours old.
• Retried on 408, 425, 429, any 5xx, and network or timeout errors.
• Not retried on other 4xx — a 401 from a broken signature check is a permanent rejection.

​

When a delivery is in doubt

​

hangup_cause values