# Webhooks overview (/webhooks)

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 [#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`](/webhooks/endpoints) | A campaign's `crmWebhookUrl` or an agent's post-call webhook |
| Events | [Every event type](/webhooks/events), 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](/webhooks/verify-signatures) (`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](/webhooks/campaign-agent-webhooks) for how those URLs work and how to move off them. There is no workspace-wide URL any more: use an endpoint.

<Callout title="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`.
</Callout>

## Quick setup [#quick-setup]

<Steps>
<Step>
### Build a receiver [#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](/webhooks/verify-signatures).
</Step>

<Step>
### Create an endpoint [#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.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
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"]
  }'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/webhook-endpoints/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/webhooks/callmitra',
    description: 'CRM sync',
    events: ['call.completed', 'call.failed', 'lead.created'],
  }),
});
const { webhookEndpoint, secret } = await res.json();
// Store `secret` now. It is not shown again.
```
</Tab>

<Tab value="Python">
```python
import os
import requests

res = requests.post(
    "https://api.callmitra.ai/api/v1/webhook-endpoints/",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    json={
        "url": "https://example.com/webhooks/callmitra",
        "description": "CRM sync",
        "events": ["call.completed", "call.failed", "lead.created"],
    },
)
body = res.json()
secret = body["secret"]  # store it now; it is not shown again
```
</Tab>
</Tabs>
</Step>

<Step>
### Store the secret [#store-the-secret]

The response includes `secret` (`whsec_…`). It appears only in this response and when you [rotate it](/webhooks/endpoints#rotate-the-signing-secret). Keep it in your secret store, for example as `CALLMITRA_WEBHOOK_SECRET`.
</Step>

<Step>
### Send a test event [#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`](/api-reference/webhooks/sendTestWebhook). CallMitra sends a signed `webhook.test` event at once and returns your server's answer.
</Step>
</Steps>

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

## What a delivery looks like [#what-a-delivery-looks-like]

```http
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](/webhooks/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](/webhooks/campaign-agent-webhooks#verify-x-signature-sha256). |

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](/webhooks/events). |

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

## Respond quickly [#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 [#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](/webhooks/endpoints#redeliver-an-event) 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 [#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}`](/api-reference/webhooks/updateWebhookEndpoint). That clears the failure count. Then [redeliver](/webhooks/endpoints#redeliver-an-event) the events you missed.

## Duplicates and ordering [#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}`](/api-reference/calls/getCall).
- 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 [#url-requirements]

- Use an absolute `https://` URL. Endpoints with `http://` are refused with [`webhook_https_required`](/errors/webhook_https_required).
- The host must resolve to a public internet address. Private, loopback and link-local addresses are refused with [`webhook_url_invalid`](/errors/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 [#next]

<Cards>
<Card href="/webhooks/endpoints" title="Managing endpoints" description="Create, update, rotate secrets, test, and use the delivery log." />

<Card href="/webhooks/events" title="Event types" description="Every event, when it fires, and a sample body." />

<Card href="/webhooks/verify-signatures" title="Verify signatures" description="Check webhook-signature in Node.js, Python, PHP and Go." />

<Card href="/webhooks/campaign-agent-webhooks" title="Campaign and agent webhooks" description="Per-campaign and per-agent webhook URLs, and how to migrate." />
</Cards>