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 endpoints | Campaign and agent webhook URLs | |
|---|---|---|
| Where you set them | Settings → Developers → Webhooks in the console, or /api/v1/webhook-endpoints | A campaign's crmWebhookUrl or an agent's post-call webhook |
| Events | Every event type, with a filter per endpoint | call.completed, call.escalated, plus callback.* and transfer.failed in some cases |
| Body | An envelope: id, type, apiVersion, createdAt, data | Flat JSON with event and timestamp at the top level |
| Signature | Standard Webhooks (webhook-signature) and X-Signature-SHA256 | X-Signature-SHA256 only |
| Delivery log and redelivery | Yes, for 30 days, in the console and the API | No |
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",…}}| Header | Meaning |
|---|---|
webhook-id | The event id (evt_ and 32 hex characters). The same on every retry and redelivery. Use it to drop duplicates. |
webhook-timestamp | When this attempt was sent, in Unix seconds. Each attempt has a new value. |
webhook-signature | One 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-Id | The same value as webhook-id. |
X-Webhook-Event | The event type, for example call.completed. |
X-Signature-SHA256 | A hex HMAC-SHA256 of the raw body, for receivers built for campaign and agent webhooks. |
The body is the event envelope:
| Field | Description |
|---|---|
id | Event id. The same as the webhook-id header. |
type | Event type, for example call.completed. |
apiVersion | Always v1 today. |
createdAt | When the event happened, ISO 8601 UTC. It does not change between retries. |
data | The 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 response | What CallMitra does |
|---|---|
2xx | Delivered. |
408, 409, 425, 429, 3xx, any 5xx, a timeout, a DNS or connection error | Retries, up to 12 attempts in total. |
Any other 4xx | Treats the event as rejected. It does not retry. |
| The URL now resolves to a private or local address | Fails at once. It does not retry. |
The wait after each failed attempt starts at 30 seconds and doubles:
| Attempt | Wait before it | About this long after the first attempt |
|---|---|---|
| 1 | — | 0 |
| 2 | 30 s | 30 s |
| 3 | 1 min | 1.5 min |
| 4 | 2 min | 3.5 min |
| 5 | 4 min | 7.5 min |
| 6 | 8 min | 15.5 min |
| 7 | 16 min | 31.5 min |
| 8 | 32 min | 1 h 4 min |
| 9 | 64 min | 2 h 8 min |
| 10 | 128 min | 4 h 16 min |
| 11 | 256 min | 8 h 32 min |
| 12 | 512 min | 17 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-idvalues 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 exampleGET /api/v1/calls/{call_id}. - A call's
call.completedandcall.failedhave 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 withhttp://are refused withwebhook_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.