Receive call webhooks

For an already configured webhook, use its receiving URL and signing secret to handle call events.

Verify the signature

Verify the signature before processing the event. Use the original request body bytes and decode the hexadecimal signing secret into bytes.

v1=hex(HMAC-SHA256(secret_bytes, timestamp + "." + raw_request_body))

This Python example uses a five-minute timestamp tolerance to reject stale deliveries. The tolerance is a receiver policy, not a webhook expiry time.

import hashlib
import hmac
import time


def verify_webhook(raw_body, headers, secret_hex):
    try:
        timestamp = int(headers["X-Webhook-Timestamp"])
        if abs(time.time() - timestamp) > 300:
            return False
        message = str(timestamp).encode("utf-8") + b"." + raw_body
        digest = hmac.new(bytes.fromhex(secret_hex), message, hashlib.sha256).hexdigest()
        return hmac.compare_digest("v1=" + digest, headers["X-Webhook-Signature"])
    except (KeyError, TypeError, ValueError):
        return False

Pass your framework’s case-insensitive request headers. Use the webhook signing secret for this check, not your Karta API key.

Accept the event

After verifying the signature, parse the JSON and save the event for processing. Return 200 OK; no response body is required. Use X-Webhook-Id to avoid processing the same delivery twice. A retry keeps the same delivery ID and receives a new timestamp and signature.

Handle retries

HTTP 4xx, 5xx, timeouts, and network failures trigger retry handling. Return 200 OK for an event you have already accepted. See Call events for headers, event names, and the payload schema.

Get started

Voice

Account

Webhooks

Receive call webhooks

Verify the signature

Accept the event

Handle retries