Webhooks

Webhooks push events to your endpoint as they occur — faster than polling, and they cost you no API requests.

Events

Event	Fires when
`call.started`	A call connects
`call.ended`	A call finishes
`call.transcript_ready`	The transcript for a call is available
`call.human_escalation`	A call is transferred to a person
`sms.received`	An inbound text arrives
`sms.sent`	An outbound text is sent
`contact.created`	A new contact is created
`contact.updated`	An existing contact changes

call.ended and call.transcript_ready are separate because transcription completes after the call does. If you need the transcript, act on call.transcript_ready — acting on call.ended and immediately fetching will often find nothing there yet.

Setting up an endpoint

Expose an HTTPS URL

It must accept POST with a JSON body and return a 2xx quickly.

Add the endpoint in the dashboard and subscribe it to the events you want. Subscribe only to what you’ll use.

Store the signing secret

You’re given a secret prefixed whsec_. Keep it in your secret manager — you need it to verify deliveries.

Verify every delivery

See below. An unverified webhook endpoint accepts anything anyone posts to it.

Payload

{
  "id": "evt_4f9c2a1e8b7d6c5a3e2f1b0d9c8a7b6e",
  "type": "call.ended",
  "created": "2026-08-02T14:32:07.412Z",
  "data": {}
}

data carries the event-specific detail. Treat unknown fields as additive — new ones may appear without notice, so parse defensively rather than rejecting on unexpected keys.

Verifying signatures

Each delivery carries an X-Webhook-Signature header: the HMAC-SHA256 of the exact raw request body, keyed with your endpoint’s signing secret, hex-encoded.

import crypto from 'crypto';

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  // Constant-time compare — never use ===
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(signature, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

<?php
function verify(string $rawBody, string $signature, string $secret): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

Compute the HMAC over the raw request body, byte for byte. Parsing the JSON and re-serializing it changes whitespace and key order, and the signature will never match. Capture the raw body before your framework parses it.

Always compare in constant time — timingSafeEqual, compare_digest, hash_equals. A plain == leaks the expected signature to a patient attacker.

Building a reliable consumer

Respond fast, work later

Verify, enqueue, return 2xx. Doing real work inline makes deliveries time out.

Be idempotent

Key on the event id and ignore ones you’ve already processed. Assume any event can arrive more than once.

Don't assume ordering

Use the created timestamp rather than arrival order. call.transcript_ready may land before you’ve finished processing call.ended.

Reject unverified payloads

Return 401 and log it. A public endpoint accepting unsigned events is an open door into your systems.

Testing

During development, point an endpoint at a request-inspection tool or an ngrok tunnel and trigger a real event — place a test call, or create a contact. Confirm you can verify the signature before writing any business logic on top.

Deactivate rather than delete

If a consumer is broken, deactivate the endpoint while you fix it. Deleting and re-creating issues a new signing secret you’d have to redeploy.

Overview

Endpoints

Automation

Events

Setting up an endpoint

Payload

Verifying signatures

Building a reliable consumer

Testing

Deactivate rather than delete

​Events

​Setting up an endpoint

​Payload

​Verifying signatures

​Building a reliable consumer

​Testing

Deactivate rather than delete

Events

Setting up an endpoint

Payload

Verifying signatures

Building a reliable consumer

Testing