Skip to Content
CallMitraDocs

Webhooks overview

Receive calls, leads, campaigns, tickets and WhatsApp messages in your system as signed HTTPS POST requests, with retries.

CallMitra sends a webhook when something happens in your workspace: a call ends, a lead is created, a campaign finishes, a ticket is resolved, a customer writes on WhatsApp. Each webhook is an HTTPS POST with a JSON body. It is signed, so you can check that it came from CallMitra. If your server does not accept it, CallMitra retries.

Two ways to receive events

Webhook endpointsCampaign and agent webhook URLs
Where you set themSettings → Developers → Webhooks in the console, or /api/v1/webhook-endpointsA campaign's crmWebhookUrl or an agent's post-call webhook
EventsEvery event type, with a filter per endpointcall.completed, call.escalated, plus callback.* and transfer.failed in some cases
BodyAn envelope: id, type, apiVersion, createdAt, dataFlat JSON with event and timestamp at the top level
SignatureStandard Webhooks (webhook-signature) and X-Signature-SHA256X-Signature-SHA256 only
Delivery log and redeliveryYes, for 30 days, in the console and the APINo

Use webhook endpoints for new integrations. The two systems are independent: when a call ends, every subscribed endpoint gets call.completed, and the campaign or agent URL for that call gets its own copy too. If you set up both and want one copy, clear that URL. See Campaign and agent webhooks for how those URLs work and how to move off them. There is no workspace-wide URL any more: use an endpoint.

WhatsApp has its own webhooks too

WhatsApp also has its own webhook endpoints, managed per WhatsApp number under WhatsApp → Developers in the console. This section covers workspace webhook endpoints. To get WhatsApp messages here, subscribe an endpoint to whatsapp.message.received.

Quick setup

Build a receiver

Add an HTTPS route on your server that accepts POST requests with a JSON body. Keep the raw body bytes: you need them to verify the signature.

Create an endpoint

In the console, open Settings → Developers → Webhooks and add the endpoint there. With the API, send your URL and the events you want. Send an empty events list (or leave it out) to get every event type.

curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/callmitra",
    "description": "CRM sync",
    "events": ["call.completed", "call.failed", "lead.created"]
  }'

Store the secret

The response includes secret (whsec_…). It appears only in this response and when you rotate it. Keep it in your secret store, for example as CALLMITRA_WEBHOOK_SECRET.

Send a test event

Use Send test event in the endpoint's menu in the console, or call POST /api/v1/webhook-endpoints/{endpoint_id}/test. CallMitra sends a signed webhook.test event at once and returns your server's answer.

Managing endpoints needs a workspace manager (or an API key created by one). An API key limited to resources needs Webhooks. See Managing endpoints.

What a delivery looks like

POST /webhooks/callmitra HTTP/1.1
Content-Type: application/json
User-Agent: CallMitra-Webhooks/1
webhook-id: evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b
webhook-timestamp: 1763184730
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
X-Webhook-Id: evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b
X-Webhook-Event: call.completed
X-Signature-SHA256: 9c1f0e…

{"id":"evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b","type":"call.completed","apiVersion":"v1","createdAt":"2026-11-15T05:31:50.412093Z","data":{"callId":"3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b",…}}
HeaderMeaning
webhook-idThe event id (evt_ and 32 hex characters). The same on every retry and redelivery. Use it to drop duplicates.
webhook-timestampWhen this attempt was sent, in Unix seconds. Each attempt has a new value.
webhook-signatureOne or more v1,<base64 signature> values, separated by spaces. There are two for 24 hours after you rotate the secret. See Verify signatures.
X-Webhook-IdThe same value as webhook-id.
X-Webhook-EventThe event type, for example call.completed.
X-Signature-SHA256A hex HMAC-SHA256 of the raw body, for receivers built for campaign and agent webhooks.

The body is the event envelope:

FieldDescription
idEvent id. The same as the webhook-id header.
typeEvent type, for example call.completed.
apiVersionAlways v1 today.
createdAtWhen the event happened, ISO 8601 UTC. It does not change between retries.
dataThe event's fields. See Event types.

New fields can be added to data at any time (see Versioning). Ignore fields you do not use.

Respond quickly

Answer with any 2xx status within 10 seconds. Do slow work, such as CRM updates or emails, after you respond, for example from a queue. CallMitra does not follow redirects, so a 3xx counts as a failed attempt. It saves the first 1 KB of your response body in the delivery log to help you debug.

Retries

Your responseWhat CallMitra does
2xxDelivered.
408, 409, 425, 429, 3xx, any 5xx, a timeout, a DNS or connection errorRetries, up to 12 attempts in total.
Any other 4xxTreats the event as rejected. It does not retry.
The URL now resolves to a private or local addressFails at once. It does not retry.

The wait after each failed attempt starts at 30 seconds and doubles:

AttemptWait before itAbout this long after the first attempt
1—0
230 s30 s
31 min1.5 min
42 min3.5 min
54 min7.5 min
68 min15.5 min
716 min31.5 min
832 min1 h 4 min
964 min2 h 8 min
10128 min4 h 16 min
11256 min8 h 32 min
12512 min17 h 4 min

After the 12th failed attempt, the delivery is marked failed. You can send it again from the delivery log for 30 days.

call.completed and call.failed wait about 20 seconds after the call ends before the first attempt, so the post-call analysis is ready. The call's data is read when that first attempt is sent.

Automatic disabling

CallMitra disables an endpoint when both of these are true:

  • At least 20 attempts in a row have failed. Retries count.
  • The endpoint has been failing for at least 24 hours with no success.

A disabled endpoint has enabled: false, a disabledReason and a disabledAt time. CallMitra alerts the workspace once when this happens: a notification in the console, plus email or WhatsApp if those alerts are turned on. New events are not queued for it. Retries that were waiting fail with endpoint disabled. Fix your receiver, then set "enabled": true with PATCH /api/v1/webhook-endpoints/{endpoint_id}. That clears the failure count. Then redeliver the events you missed.

Duplicates and ordering

  • Expect duplicates. If your server handles an event but answers too late, CallMitra retries it. A redelivery also sends the same event again. Store the webhook-id values you have handled and skip repeats.
  • Expect any order. Deliveries are sent in parallel, and a retry can arrive after a newer event. Use createdAt, or fetch the current state from the API, for example GET /api/v1/calls/{call_id}.
  • A call's call.completed and call.failed have different ids. Each is queued once per endpoint, even when the call end is reported twice internally.

URL requirements

  • Use an absolute https:// URL. Endpoints with http:// are refused with webhook_https_required.
  • The host must resolve to a public internet address. Private, loopback and link-local addresses are refused with webhook_url_invalid, as are URLs with a username or password. CallMitra checks the address again before each attempt.
  • A workspace can have up to 20 endpoints.

Next

On this page