Skip to Content
CallMitraDocs

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.

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 or api_key_scope_denied. A request that is not tied to a workspace gets webhook_workspace_required.

Create an endpoint

FieldTypeRequiredDescription
urlstringYesPublic https:// URL, up to 2048 characters. See URL requirements.
descriptionstringNoA label for you, up to 500 characters. Default "".
eventsstring[]NoEvent types to receive, up to 50. Empty or left out means every event type. See Event types.
enabledbooleanNoDefault 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.

ErrorWhen
webhook_https_requiredThe URL is not https://.
webhook_url_invalidThe URL is not absolute, has a username or password, or resolves to a private or local address.
webhook_event_type_unknownevents contains a type that does not exist, or webhook.test.
webhook_endpoint_limit_reachedThe workspace already has 20 endpoints.
idempotency_key_reusedYou sent the same Idempotency-Key with a different body.

Endpoint fields

FieldDescription
idEndpoint id.
urlWhere events are sent.
descriptionYour label.
eventsSubscribed event types. Empty means every event type.
enabledfalse when you paused it or CallMitra disabled it.
disabledReasonWhy CallMitra disabled it, for example Disabled after 20 failed deliveries in a row over 24 hours (last: HTTP 500).
disabledAtWhen CallMitra disabled it.
consecutiveFailuresFailed attempts in a row since the last success. Retries count.
lastStatusResult of the latest attempt, such as HTTP 200 or timeout.
lastSuccessAtTime of the latest successful attempt.
lastFailureAtTime of the latest failed attempt.
previousSecretExpiresAtAfter a rotation, the time until which the old secret also signs deliveries.
createdAt, updatedAtISO 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 parameterDescription
endpointIdOnly deliveries to this endpoint. An unknown id returns webhook_endpoint_not_found.
eventTypeOnly this event type, for example call.completed.
statuspending, processing, delivered or failed. Any other value returns parameter_invalid.
limitDeliveries per page, 1 to 100. Default 25.
cursornextCursor 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"
StatusMeaning
pendingWaiting for its first attempt or its next retry. See nextAttemptAt.
processingAn attempt is being sent now.
deliveredYour server answered 2xx. Final.
failedRejected with a non-retryable status, out of attempts, or stopped (for example the endpoint was disabled). Final.
FieldDescription
idDelivery id.
eventIdEvent id (evt_…). The webhook-id header.
eventTypeEvent type.
endpointIdEndpoint it is sent to.
statusSee the table above.
attemptsAttempts made so far, up to 12.
lastStatusCodeHTTP status from the last attempt. null if no response was received.
lastErrorWhy the last attempt failed, such as HTTP 500 or timeout. Empty on success.
responseSnippetFirst 1 KB of your last response body.
latencyMsHow long the last attempt took.
nextAttemptAtWhen the next attempt is due. Only while pending.
lastAttemptAtTime of the last attempt.
deliveredAtWhen your server accepted the event.
createdAtWhen the delivery was queued.
payloadThe 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.

On this page