Managing endpoints
Create, update and delete webhook endpoints, rotate signing secrets, send test events, and use the delivery log to inspect and redeliver events.
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/ |
| List endpoints | GET /api/v1/webhook-endpoints/ |
| Get one endpoint | GET /api/v1/webhook-endpoints/{endpoint_id} |
| Update an endpoint | PATCH /api/v1/webhook-endpoints/{endpoint_id} |
| Delete an endpoint | DELETE /api/v1/webhook-endpoints/{endpoint_id} |
| Rotate the secret | POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret |
| Send a test event | POST /api/v1/webhook-endpoints/{endpoint_id}/test |
| List event types | GET /api/v1/webhook-event-types/ |
| List deliveries | GET /api/v1/webhook-deliveries/ |
| Get one delivery | GET /api/v1/webhook-deliveries/{delivery_id} |
| Redeliver an event | POST /api/v1/webhook-deliveries/{delivery_id}/redeliver |
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
GETrequests.
Without the right access you get permission_denied or api_key_scope_denied. A request that is not tied to a workspace gets webhook_workspace_required.
Create an endpoint
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Public https:// URL, up to 2048 characters. See 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. |
enabled | boolean | No | Default true. Send false to create the endpoint without sending to it yet. |
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"]
}'The Idempotency-Key header is optional. With it, a retried create request does not make a second endpoint. See Idempotency.
{
"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="
}The secret is shown once
secret appears only in this response and in the response to a rotation. CallMitra stores it encrypted and never returns it again. If you lose it, rotate the secret.
| Error | When |
|---|---|
webhook_https_required | The URL is not https://. |
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 | events contains a type that does not exist, or webhook.test. |
webhook_endpoint_limit_reached | The workspace already has 20 endpoints. |
idempotency_key_reused | You sent the same Idempotency-Key with a different body. |
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. |
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
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.
curl https://api.callmitra.ai/api/v1/webhook-endpoints/ \
-H "X-API-Key: $CALLMITRA_API_KEY"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 the ones you need.
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"]}'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
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.
webhook-signature: v1,Q3VycmVudFNpZ25hdHVyZUJhc2U2NA== v1,T2xkU2lnbmF0dXJlQmFzZTY0QmFzZQ==Rotate
Call rotate-secret and store the new secret.
Deploy
Update your receiver to use the new secret. A receiver that checks every signature in the header accepts deliveries during the whole switch.
Wait
After previousSecretExpiresAt, only the new secret signs deliveries.
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.
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.
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.
curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c/test \
-H "X-API-Key: $CALLMITRA_API_KEY"{
"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; enable it first. You cannot subscribe to webhook.test.
List event types
GET /api/v1/webhook-event-types/ returns every type you can put in events, with a short description.
{
"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 for when each one fires and what it contains.
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. |
eventType | Only this event type, for example call.completed. |
status | pending, processing, delivered or failed. Any other value returns 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.
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"| 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 /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.
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.
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. The new delivery gets the full retry schedule.
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 with Retry-After. To catch up on many events, space out the redeliveries.
To catch up after an outage: re-enable the endpoint, list deliveries with status=failed for it, and redeliver each one.