# Managing endpoints (/webhooks/endpoints)

A webhook endpoint is a URL plus a list of event types. CallMitra signs every delivery to it with the endpoint's own secret. You can manage endpoints in the console or with the API.

**In the console**, open **Settings → Developers → Webhooks**. A manager can create, edit and delete endpoints, pick event types, copy the signing secret (shown once), send a test event, and browse the delivery log and redeliver events.

**With the API**, use the requests below. All paths are under `https://api.callmitra.ai`.

| Task | Request |
| --- | --- |
| Create an endpoint | [`POST /api/v1/webhook-endpoints/`](/api-reference/webhooks/createWebhookEndpoint) |
| List endpoints | [`GET /api/v1/webhook-endpoints/`](/api-reference/webhooks/listWebhookEndpoints) |
| Get one endpoint | [`GET /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/getWebhookEndpoint) |
| Update an endpoint | [`PATCH /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/updateWebhookEndpoint) |
| Delete an endpoint | [`DELETE /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/deleteWebhookEndpoint) |
| Rotate the secret | [`POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret`](/api-reference/webhooks/rotateWebhookEndpointSecret) |
| Send a test event | [`POST /api/v1/webhook-endpoints/{endpoint_id}/test`](/api-reference/webhooks/sendTestWebhook) |
| List event types | [`GET /api/v1/webhook-event-types/`](/api-reference/webhooks/listWebhookEventTypes) |
| List deliveries | [`GET /api/v1/webhook-deliveries/`](/api-reference/webhooks/listWebhookDeliveries) |
| Get one delivery | [`GET /api/v1/webhook-deliveries/{delivery_id}`](/api-reference/webhooks/getWebhookDelivery) |
| Redeliver an event | [`POST /api/v1/webhook-deliveries/{delivery_id}/redeliver`](/api-reference/webhooks/redeliverWebhook) |

## Permissions [#permissions]

- **Reading** (list and get endpoints, deliveries and event types) works for any member of the workspace.
- **Changing** (create, update, delete, rotate, test and redeliver) needs a workspace **manager**. An API key acts with the role of the user who created it.
- An API key limited to certain resources needs the **Webhooks** resource. A read-only key can only send `GET` requests.

Without the right access you get [`permission_denied`](/errors/permission_denied) or [`api_key_scope_denied`](/errors/api_key_scope_denied). A request that is not tied to a workspace gets [`webhook_workspace_required`](/errors/webhook_workspace_required).

## Create an endpoint [#create-an-endpoint]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | Yes | Public `https://` URL, up to 2048 characters. See [URL requirements](/webhooks#url-requirements). |
| `description` | string | No | A label for you, up to 500 characters. Default `""`. |
| `events` | string[] | No | Event types to receive, up to 50. Empty or left out means every event type. See [Event types](/webhooks/events). |
| `enabled` | boolean | No | Default `true`. Send `false` to create the endpoint without sending to it yet. |

<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" \
  -H "Idempotency-Key: 6a1d0f3e-create-crm-endpoint" \
  -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',
    'Idempotency-Key': '6a1d0f3e-create-crm-endpoint',
  },
  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"],
        "Idempotency-Key": "6a1d0f3e-create-crm-endpoint",
    },
    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>

The `Idempotency-Key` header is optional. With it, a retried create request does not make a second endpoint. See [Idempotency](/idempotency).

```json
{
  "success": true,
  "webhookEndpoint": {
    "id": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c",
    "url": "https://example.com/webhooks/callmitra",
    "description": "CRM sync",
    "events": ["call.completed", "call.failed", "lead.created"],
    "enabled": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "lastStatus": "",
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "previousSecretExpiresAt": null,
    "createdAt": "2026-11-15T05:30:00.000000+00:00",
    "updatedAt": "2026-11-15T05:30:00.000000+00:00"
  },
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8m1gTzZ4dKo="
}
```

<Callout type="warn" title="The secret is shown once">
`secret` appears only in this response and in the response to a [rotation](#rotate-the-signing-secret). CallMitra stores it encrypted and never returns it again. If you lose it, rotate the secret.
</Callout>

| Error | When |
| --- | --- |
| [`webhook_https_required`](/errors/webhook_https_required) | The URL is not `https://`. |
| [`webhook_url_invalid`](/errors/webhook_url_invalid) | The URL is not absolute, has a username or password, or resolves to a private or local address. |
| [`webhook_event_type_unknown`](/errors/webhook_event_type_unknown) | `events` contains a type that does not exist, or `webhook.test`. |
| [`webhook_endpoint_limit_reached`](/errors/webhook_endpoint_limit_reached) | The workspace already has 20 endpoints. |
| [`idempotency_key_reused`](/errors/idempotency_key_reused) | You sent the same `Idempotency-Key` with a different body. |

## Endpoint fields [#endpoint-fields]

| Field | Description |
| --- | --- |
| `id` | Endpoint id. |
| `url` | Where events are sent. |
| `description` | Your label. |
| `events` | Subscribed event types. Empty means every event type. |
| `enabled` | `false` when you paused it or CallMitra [disabled it](/webhooks#automatic-disabling). |
| `disabledReason` | Why CallMitra disabled it, for example `Disabled after 20 failed deliveries in a row over 24 hours (last: HTTP 500).` |
| `disabledAt` | When CallMitra disabled it. |
| `consecutiveFailures` | Failed attempts in a row since the last success. Retries count. |
| `lastStatus` | Result of the latest attempt, such as `HTTP 200` or `timeout`. |
| `lastSuccessAt` | Time of the latest successful attempt. |
| `lastFailureAt` | Time of the latest failed attempt. |
| `previousSecretExpiresAt` | After a rotation, the time until which the old secret also signs deliveries. |
| `createdAt`, `updatedAt` | ISO 8601 times. |

## List and get endpoints [#list-and-get-endpoints]

`GET /api/v1/webhook-endpoints/` returns every endpoint of the workspace in one page, as `webhookEndpoints`. `nextCursor` is always `null` and `hasMore` is always `false`. `GET /api/v1/webhook-endpoints/{endpoint_id}` returns one endpoint as `webhookEndpoint`, or [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found).

```bash
curl https://api.callmitra.ai/api/v1/webhook-endpoints/ \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

## Update an endpoint [#update-an-endpoint]

`PATCH` changes only the fields you send: `url`, `description`, `events` or `enabled`. A new `events` list replaces the old one. A new `url` goes through the same checks as on create.

Setting `"enabled": true` on a disabled endpoint clears `disabledReason`, `disabledAt` and the failure count. New events start to arrive again. Events from the time it was disabled are not queued again; [redeliver](#redeliver-an-event) the ones you need.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -X PATCH https://api.callmitra.ai/api/v1/webhook-endpoints/7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "events": ["call.completed", "call.failed"]}'
```
</Tab>

<Tab value="Node.js">
```js
const endpointId = '7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c';
const res = await fetch(`https://api.callmitra.ai/api/v1/webhook-endpoints/${endpointId}`, {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ enabled: true, events: ['call.completed', 'call.failed'] }),
});
const { webhookEndpoint } = await res.json();
```
</Tab>

<Tab value="Python">
```python
endpoint_id = "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c"
res = requests.patch(
    f"https://api.callmitra.ai/api/v1/webhook-endpoints/{endpoint_id}",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    json={"enabled": True, "events": ["call.completed", "call.failed"]},
)
endpoint = res.json()["webhookEndpoint"]
```
</Tab>
</Tabs>

## Delete an endpoint [#delete-an-endpoint]

`DELETE /api/v1/webhook-endpoints/{endpoint_id}` stops deliveries to it at once, including pending retries. It also deletes the endpoint's delivery history. The response is `{"success": true, "id": "…", "deleted": true}`.

To stop deliveries but keep the history, set `"enabled": false` instead.

## Rotate the signing secret [#rotate-the-signing-secret]

`POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` returns a new `secret`, once, in the same shape as the create response.

For the next **24 hours**, the old secret keeps working. Each delivery carries two signatures in `webhook-signature`: the new one first, then the old one. `previousSecretExpiresAt` shows when the old secret stops. This gives you time to deploy the new secret without failing any delivery.

```http
webhook-signature: v1,Q3VycmVudFNpZ25hdHVyZUJhc2U2NA== v1,T2xkU2lnbmF0dXJlQmFzZTY0QmFzZQ==
```

<Steps>
<Step>
### Rotate [#rotate]

Call `rotate-secret` and store the new secret.
</Step>

<Step>
### Deploy [#deploy]

Update your receiver to use the new secret. A receiver that [checks every signature in the header](/webhooks/verify-signatures) accepts deliveries during the whole switch.
</Step>

<Step>
### Wait [#wait]

After `previousSecretExpiresAt`, only the new secret signs deliveries.
</Step>
</Steps>

<Callout type="warn" title="Rotate once at a time">
Rotating again within 24 hours makes the secret you just replaced the "old" one. The secret before it stops working at once.
</Callout>

The `X-Signature-SHA256` header is signed with the **new** secret only, from the moment you rotate. If your receiver checks that header, deploy the new secret first. See [Verify X-Signature-SHA256](/webhooks/campaign-agent-webhooks#verify-x-signature-sha256).

## Send a test event [#send-a-test-event]

`POST /api/v1/webhook-endpoints/{endpoint_id}/test` sends a signed `webhook.test` event to the endpoint at once, whatever its `events` filter. The request waits for the attempt and returns the delivery, with your server's answer and the payload that was sent.

```bash
curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c/test \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

```json
{
  "success": true,
  "webhookDelivery": {
    "id": "0b9d6c2e-3f41-4a7b-8e5d-9c1f2a3b4d5e",
    "eventId": "evt_2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b",
    "eventType": "webhook.test",
    "endpointId": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c",
    "status": "delivered",
    "attempts": 1,
    "lastStatusCode": 200,
    "lastError": "",
    "responseSnippet": "ok",
    "latencyMs": 184,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-11-15T05:35:12.004211+00:00",
    "deliveredAt": "2026-11-15T05:35:12.004211+00:00",
    "createdAt": "2026-11-15T05:35:11.812930+00:00",
    "payload": {
      "id": "evt_2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b",
      "type": "webhook.test",
      "apiVersion": "v1",
      "createdAt": "2026-11-15T05:35:11.810422Z",
      "data": {
        "endpointId": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c",
        "message": "This is a test event from Call Mitra."
      }
    }
  }
}
```

If your server fails the test, `status` is `pending` and the test is retried like any other delivery. A disabled endpoint returns [`webhook_endpoint_disabled`](/errors/webhook_endpoint_disabled); enable it first. You cannot subscribe to `webhook.test`.

## List event types [#list-event-types]

`GET /api/v1/webhook-event-types/` returns every type you can put in `events`, with a short description.

```json
{
  "success": true,
  "eventTypes": [
    { "type": "call.completed", "description": "A call ended (any final status). Sent after post-call analysis." },
    { "type": "call.failed", "description": "A call ended without connecting: busy, no answer or carrier failure. Sent with call.completed." },
    { "type": "call.escalated", "description": "The agent transferred the caller to a person." }
  ]
}
```

See [Event types](/webhooks/events) for when each one fires and what it contains.

## Delivery log [#delivery-log]

Each time CallMitra queues an event for an endpoint, it creates a **delivery**. Retries update the same delivery. A redelivery creates a new one.

`GET /api/v1/webhook-deliveries/` lists deliveries, newest first.

| Query parameter | Description |
| --- | --- |
| `endpointId` | Only deliveries to this endpoint. An unknown id returns [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found). |
| `eventType` | Only this event type, for example `call.completed`. |
| `status` | `pending`, `processing`, `delivered` or `failed`. Any other value returns [`parameter_invalid`](/errors/parameter_invalid). |
| `limit` | Deliveries per page, 1 to 100. Default 25. |
| `cursor` | `nextCursor` from the previous page. |

The response has `webhookDeliveries`, `nextCursor` and `hasMore`. While `hasMore` is `true`, pass `nextCursor` as `cursor` to get the next page. List items do not include `payload`.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -G https://api.callmitra.ai/api/v1/webhook-deliveries/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  --data-urlencode "endpointId=7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c" \
  --data-urlencode "status=failed" \
  --data-urlencode "limit=50"
```
</Tab>

<Tab value="Node.js">
```js
const failed = [];
let cursor;
do {
  const params = new URLSearchParams({ status: 'failed', limit: '100' });
  if (cursor) params.set('cursor', cursor);
  const res = await fetch(`https://api.callmitra.ai/api/v1/webhook-deliveries/?${params}`, {
    headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY },
  });
  const page = await res.json();
  failed.push(...page.webhookDeliveries);
  cursor = page.hasMore ? page.nextCursor : undefined;
} while (cursor);
```
</Tab>

<Tab value="Python">
```python
failed, cursor = [], None
while True:
    params = {"status": "failed", "limit": 100}
    if cursor:
        params["cursor"] = cursor
    page = requests.get(
        "https://api.callmitra.ai/api/v1/webhook-deliveries/",
        headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
        params=params,
    ).json()
    failed.extend(page["webhookDeliveries"])
    if not page["hasMore"]:
        break
    cursor = page["nextCursor"]
```
</Tab>
</Tabs>

| Status | Meaning |
| --- | --- |
| `pending` | Waiting for its first attempt or its next retry. See `nextAttemptAt`. |
| `processing` | An attempt is being sent now. |
| `delivered` | Your server answered `2xx`. Final. |
| `failed` | Rejected with a non-retryable status, out of attempts, or stopped (for example the endpoint was disabled). Final. |

| Field | Description |
| --- | --- |
| `id` | Delivery id. |
| `eventId` | Event id (`evt_…`). The `webhook-id` header. |
| `eventType` | Event type. |
| `endpointId` | Endpoint it is sent to. |
| `status` | See the table above. |
| `attempts` | Attempts made so far, up to 12. |
| `lastStatusCode` | HTTP status from the last attempt. `null` if no response was received. |
| `lastError` | Why the last attempt failed, such as `HTTP 500` or `timeout`. Empty on success. |
| `responseSnippet` | First 1 KB of your last response body. |
| `latencyMs` | How long the last attempt took. |
| `nextAttemptAt` | When the next attempt is due. Only while `pending`. |
| `lastAttemptAt` | Time of the last attempt. |
| `deliveredAt` | When your server accepted the event. |
| `createdAt` | When the delivery was queued. |
| `payload` | The exact envelope that was signed and sent. Only on a single delivery, not in lists. |

Delivered and failed deliveries are deleted after **30 days**.

## Get a delivery [#get-a-delivery]

`GET /api/v1/webhook-deliveries/{delivery_id}` returns one delivery as `webhookDelivery`, including `payload`. Use it to see exactly what was sent. An unknown id returns [`webhook_delivery_not_found`](/errors/webhook_delivery_not_found).

## Redeliver an event [#redeliver-an-event]

`POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` queues the same event to the same endpoint again, due now. It creates a **new** delivery with the same `eventId` and `payload` and returns it (usually with `status: "pending"`). The `webhook-id` header is the same as before, so a receiver that drops duplicates ignores events it already handled.

```bash
curl -X POST https://api.callmitra.ai/api/v1/webhook-deliveries/0b9d6c2e-3f41-4a7b-8e5d-9c1f2a3b4d5e/redeliver \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

The endpoint must be enabled, or you get [`webhook_endpoint_disabled`](/errors/webhook_endpoint_disabled). The new delivery gets the full retry schedule.

<Callout title="Manual sends are capped">
Test events and redeliveries share a limit of **10 per endpoint per minute**, from the console and the API combined. Above it you get `429` [`rate_limit_exceeded`](/errors/rate_limit_exceeded) with `Retry-After`. To catch up on many events, space out the redeliveries.
</Callout>

To catch up after an outage: re-enable the endpoint, list deliveries with `status=failed` for it, and redeliver each one.