Webhook Subscriptions
Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.
Configure webhook endpoints to receive call_voice.* events as calls progress.
Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes. Each event includes a unique ID for deduplication.
Webhook Headers
All webhook requests include two sets of headers. If you have an existing integration
using the X-Webhook-* headers, nothing changes — those headers are still sent on
every delivery and work exactly as before. The new webhook-* headers follow the
Standard Webhooks specification.
You can safely ignore them if your current verification code works and you don’t want to use this convention.
Standard Webhooks Headers (Recommended)
Used by our SDK and any Standard Webhooks library.
| Header | Description |
|---|---|
webhook-id | Unique event identifier (use as idempotency key) |
webhook-timestamp | Unix timestamp (seconds) when the webhook was sent |
webhook-signature | Standard Webhooks signature (v1,{base64} format) |
Legacy Headers (Deprecated)
Still sent on every delivery for backwards compatibility. Existing verification code using these headers continues to work — no changes required.
| Header | Description |
|---|---|
X-Webhook-Event | (deprecated) Event type (e.g., call_voice.ringing) |
X-Webhook-Subscription-ID | (deprecated) Webhook subscription ID |
X-Webhook-Timestamp | (deprecated) Unix timestamp (seconds) |
X-Webhook-Signature | (deprecated) HMAC-SHA256 signature (hex-encoded) |
Signing Secrets
Signing secrets use the Standard Webhooks format: a whsec_ prefix followed
by base64-encoded random bytes (e.g., whsec_bGlucS1leGFtcGxlLXNlY3JldC1kby1ub3QtdXNlLTMyYg==).
Strip the whsec_ prefix and base64-decode the remainder to get the raw key bytes.
Verifying Webhook Signatures
Webhooks are signed following the Standard Webhooks specification. You can use any Standard Webhooks library to verify signatures, or implement verification manually:
Signed content: {webhook-id}.{webhook-timestamp}.{body}
Verification Steps:
- Extract the
webhook-id,webhook-timestamp, andwebhook-signatureheaders - Reject if the timestamp is more than 5 minutes from the current time, in either direction (replay protection)
- Get the raw request body bytes (do not parse and re-serialize)
- Construct signed content:
"{webhook-id}.{webhook-timestamp}.{body}" - Strip the
whsec_prefix from your secret and base64-decode to get key bytes - Compute HMAC-SHA256 using the key bytes over the signed content
- Base64-encode the result and compare with the value after
v1,inwebhook-signature - Use constant-time comparison to prevent timing attacks
Example (Python):
import base64, hashlib, hmac, time
TOLERANCE_SECONDS = 5 * 60
def verify_webhook(secret: str, body: bytes, headers) -> bool:
# body: the raw request body bytes, before any JSON parsing (Flask: request.get_data())
msg_id = headers.get('webhook-id')
timestamp = headers.get('webhook-timestamp')
signature = headers.get('webhook-signature')
if not (msg_id and timestamp and signature):
return False
try:
sent_at = int(timestamp)
except ValueError:
return False
if abs(time.time() - sent_at) > TOLERANCE_SECONDS:
return False # stale or from the future: possible replay
key = base64.b64decode(secret.removeprefix('whsec_'))
signed_content = f'{msg_id}.{timestamp}.'.encode() + body
expected = base64.b64encode(
hmac.new(key, signed_content, hashlib.sha256).digest()
)
for sig in signature.split(' '):
version, _, value = sig.partition(',')
if version == 'v1' and hmac.compare_digest(expected, value.encode()):
return True
return False
Example (Node.js):
const crypto = require('crypto');
const TOLERANCE_SECONDS = 5 * 60;
// rawBody: the request body exactly as received, as a Buffer or string
// (Express: express.raw({ type: 'application/json' })), not parsed JSON.
function verifyWebhook(secret, rawBody, headers) {
const msgId = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signature = headers['webhook-signature'];
if (!msgId || !timestamp || !signature) return false;
if (!/^\d+$/.test(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
return false; // stale or from the future: possible replay
}
const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
const key = Buffer.from(secretStr, 'base64');
const expected = crypto
.createHmac('sha256', key)
.update(`${msgId}.${timestamp}.`)
.update(rawBody)
.digest();
return signature.split(' ').some((sig) => {
if (!sig.startsWith('v1,')) return false;
const received = Buffer.from(sig.slice(3), 'base64');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Security Best Practices:
- Reject webhooks whose timestamp is more than 5 minutes from the current time, to prevent replay attacks
- Always use constant-time comparison for signature verification
- Store your signing secret securely (e.g., environment variable, secrets manager)
- Return a 2xx status code quickly, then process the webhook asynchronously