Skip to main content
API Reference

Webhooks

Create outbound webhook subscriptions, the event catalogue with each payload (calls, conversations, payments, and CRM record changes for contacts, companies, leads, deals, tasks and notes), signature verification, test deliveries, and the delivery log with replay.

Subscribe an HTTPS endpoint to platform events. Every payload is signed with HMAC-SHA256 using the subscription's secret. Deliveries are logged, inspectable, and replayable.

Credential class: dashboard JWT or a cm_ key with webhooks:write

These routes accept either credential.

Authorization: Bearer <jwt_access_token>
# or
Authorization: Bearer cm_your_api_key
CallerRequirement
cm_ API keyMust carry the webhooks:write scope. Every endpoint on this page checks it, including the read-only list and delivery endpoints - there is no webhooks:read scope
Dashboard JWTEvery endpoint, including the reads, requires owner or admin (403 Only owners/admins can manage webhooks otherwise). Delivery payloads carry customer data, so the log is not open to every member

Base URL for every example: https://api.callmissed.com. Errors are {"detail": "..."}.

Event types

Pass these in the events array. An unrecognised value returns 422 listing the valid set. Duplicates are dropped, and the array may hold at most as many entries as the catalogue below (50).

CategoryEvents
Conversations & messagesconversation.started, conversation.ended, message.received, message.sent, message.status (a WhatsApp message you sent reached sent, delivered, read or failed, see delivery status)
Voice sessionsvoice_session.started, voice_session.ended, voice_session.failed
Telephony call lifecyclecall.started, call.completed, call.failed, call.amd_detected (answering-machine detection resolved on an outbound call), call.handoff (an agent squad member handed a live call to another member), call.moderation_flagged (caller or agent speech matched a moderation category)
Post-call analysisvoice_analysis.completed
Outbound campaignscampaign.started, campaign.completed, campaign.failed
Metric alertsvoice_alert.triggered
Billingbudget.alert, budget.exceeded, credits.low
Keysapi_key.expired
Invoices & paymentsinvoice.created, payment.succeeded, payment.failed
Customer payment linkspayment_request.partially_paid, payment_request.paid, payment_request.expired, payment_request.cancelled — a payment link an agent sent to your customer changed status in your own connected Razorpay account
CRM quotes & invoicesquote.accepted (a customer accepted a quote on its public page, or your team recorded the acceptance), invoice.paid (a CRM invoice was fully paid, online through its payment link or by a recorded manual payment)
CRM recordscontact.created, contact.updated, contact.deleted, company.created, company.updated, company.deleted, lead.created, lead.updated, lead.deleted, deal.created, deal.updated, deal.deleted, task.created, task.updated, task.deleted, note.created, note.updated, note.deleted — a CRM record was created, changed or deleted by anyone, see CRM record events

Conversation and message events

Sent once the change is saved, on every channel that keeps a conversation thread: WhatsApp, Instagram, Facebook Messenger, the website chat widget, and a phone call handed to a person. A subscription scoped to one agent receives the events of that agent's conversations.

EventWhendata fields
conversation.startedA new conversation thread opens (the customer's first message, or your first message to them)conversation_id, bot_id, channel (whatsapp, instagram, facebook, web or voice), external_id (the customer on that channel: phone number or WhatsApp id, platform user id, or chat session id), contact_id (or null), started_at
conversation.endedAn open conversation is set to completed or failed, from the inbox, the API or the agentconversation_id, bot_id, channel, external_id, status, ended_at
message.receivedA customer's message is storedconversation_id, bot_id, channel, from, message_id, type, text (null for media without a caption). WhatsApp adds from_user_id and username
message.sentA message to the customer is storedconversation_id, bot_id, channel, to, message_id, type, text, sent_by (ai for your agent, agent for a person in the inbox, api for an API call, campaign for a campaign send)

message_id is the channel's own message id when it has one (for WhatsApp, the id that message.status reports on), otherwise the CallMissed message id. Reopening a conversation does not send an event.

Payment events

Sent after the payment's outcome is saved, for payments on your own CallMissed account (plan purchases, renewals and credit top-ups, including automatic recharges). Each event is sent at most once per order_id, but one order can send both: a payment that is declined and then retried successfully sends payment.failed and later payment.succeeded.

amount is in major units of currency (999.0 is ₹999.00), not the minor units the CRM quote and invoice events use.

Eventdata fields
payment.succeededorder_id, amount (major units), currency, type (plan or credit_topup), plan (or null for a top-up), credits (credits the payment added), invoice_number (or null for a renewal, whose invoice follows separately), recurring (true for a subscription charge)
payment.failedorder_id, amount, currency, type, plan, reason (why the payment did not go through, or null)

CRM quote and invoice events

Both are sent once the change is saved. Money is in minor units of the document's currency (unlike the payment events, which use major units); ids are your own records.

Eventdata fields
quote.acceptedquote_id, number, status (converted when the quote was turned straight into an issued invoice, else accepted), currency, total_minor, accepted_by_name, accepted_at, contact_id, deal_id, invoice_id (the issued invoice, or null)
invoice.paidinvoice_id, number, status (paid), currency, total_minor, amount_paid_minor, contact_id, deal_id, paid_at

Call lifecycle events

call.started is sent when the other side answers, call.completed when the call's status becomes completed, and call.failed when it becomes failed, busy or no_answer. A subscription scoped to one agent receives that agent's calls only.

data fieldTypeMeaning
call_idUUIDThe call. Use it with GET /api/v1/telephony/calls/{call_id}, its transcript and its recording
directionstringinbound or outbound
statusstringin_progress, completed, failed, busy or no_answer
bot_idUUID | nullThe agent on the call
remote_e164string | nullThe other party's phone number
voice_session_idUUID | nullThe agent's voice session, once the call has one. voice_analysis.completed reports on the same id as session_id
hangup_cause_codeinteger | nullThe carrier's hang-up cause, when known

CRM record events

Eighteen events: contact, company, lead, deal, task and note, each with .created, .updated and .deleted. One event is sent per record written, whoever wrote it, once the change is saved. Use them to keep another system in step with your CallMissed CRM; the end-to-end flow is in Connect your CRM.

CRM records belong to no single agent, so these events go to workspace-wide subscriptions only. A subscription with a bot_id does not receive them.

Two rules apply to these eighteen events and to no others:

  • They must be named. A subscription receives a CRM record event only when its events list names it. A subscription whose events is empty ("every event") still receives none of them, so that customer records are sent only to endpoints that asked for them.
  • An API key needs the record's read scope to subscribe. The event delivers the same JSON as the record's GET, so creating or updating a subscription that names one needs, besides webhooks:write, the scope below. 403 API key missing required scope: … otherwise. Console owners and admins are not scope-checked.
EventsScope the subscribing API key also needs
contact.*contacts:read
company.*companies:read
lead.*crm_leads:read
deal.*crm_deals:read
task.*crm_tasks:read
note.*crm_notes:read
{
  "event": "contact.updated",
  "data": {
    "event": "contact.updated",
    "id": "44110c7e-2a51-4c0f-9d3b-6f1e2a7b8c90",
    "occurred_at": "2026-11-17T06:31:10.498211+00:00",
    "source": "agent",
    "contact": {
      "id": "44110c7e-2a51-4c0f-9d3b-6f1e2a7b8c90",
      "tenant_id": "a0b1c2d3-4455-6677-8899-aabbccddeeff",
      "company_id": null,
      "phone": "+919876543210",
      "email": "[email protected]",
      "name": "Asha Menon",
      "external_ids": { "hubspot": "123" },
      "whatsapp_opt_in": true,
      "email_opt_in": false,
      "sms_opt_in": false,
      "consent_source": "hubspot_sync",
      "consent_updated_at": "2026-11-17T06:31:10.412000Z",
      "whatsapp_bsuid": null,
      "whatsapp_parent_bsuid": null,
      "whatsapp_username": null,
      "lifecycle_stage": "qualified",
      "lead_source": null,
      "owner_user_id": null,
      "tags": ["vip"],
      "metadata": null,
      "created_at": "2026-11-17T06:31:10.412000Z",
      "updated_at": "2026-11-17T09:02:44.120000Z"
    }
  },
  "timestamp": "2026-11-17T09:02:44.301554+00:00"
}
data fieldTypeMeaning
eventstringThe event name again, e.g. contact.updated
idUUIDThe record's id
occurred_atdatetimeWhen the change was saved (ISO 8601, UTC)
sourcestringWho made the change, see below
contact / company / lead / deal / task / noteobjectOne key, named after the record type. On created and updated it is the record exactly as its GET returns it: the contact, company, lead, deal, task or note object. A contact here has no score / score_grade; those are on the contact list only
sourceThe change was made by
apiA request with a cm_ API key, including the account MCP server
consoleA signed-in person in the console, including the console assistant
agentAn AI agent during a call or chat, or a post-call rule that ran on a call's result
importA CSV import
systemAnything else: a connected integration, a payment event, automatic clean-up

If your own integration writes with an API key, its writes come back to you as source: "api". Skip those to avoid an update loop.

Deleted events. The record is gone, so the object under the record key carries only what identifies it:

EventObject under the record key
contact.deleted, company.deletedid, external_ids (your own ids), and merged_into when the delete was caused by a merge
lead.deletedid, external_ref
deal.deleted, task.deleted, note.deletedid
{
  "event": "contact.deleted",
  "data": {
    "event": "contact.deleted",
    "id": "9922aa01-77b4-4e2c-8a10-0c5d6e7f8a9b",
    "occurred_at": "2026-11-17T09:10:02.118400+00:00",
    "source": "console",
    "contact": {
      "id": "9922aa01-77b4-4e2c-8a10-0c5d6e7f8a9b",
      "external_ids": { "hubspot": "456" },
      "merged_into": "44110c7e-2a51-4c0f-9d3b-6f1e2a7b8c90"
    }
  },
  "timestamp": "2026-11-17T09:10:02.240913+00:00"
}

merged_into is the id of the surviving record. When it is present, repoint your link to that record instead of deleting your copy. The survivor sends its own updated event when the merge filled any of its blank fields.

Which writes send what.

WriteEvents
Create, update or delete one record (API, console, agent tool)One event for that record
Create-or-updatecreated or updated, matching the response's created flag
Move a deal, complete a taskdeal.updated, task.updated
Convert a leadlead.updated, contact.created or contact.updated, company.created when a company was created, deal.created when a deal was
Bulk update, delete or tagOne event per record
CSV importOne event per record, source: "import". A record the file created and then touched again sends one created
Mergedeleted with merged_into for each duplicate, and updated for the survivor when fields were filled

Not announced. Rows that only follow their parent do not send their own events: the notes of a deleted record, tasks detached from a deleted record, notes and tasks moved to another record by a merge or a lead conversion, and links cleared on other records when the record they pointed at is deleted. Erasing a whole account sends nothing. A contact that first appears through an inbound WhatsApp message does not send contact.created yet; an updated_after pull on the contact list returns it.

Bursts and order. An import or a bulk action can queue thousands of these events at once. They are sent to each endpoint a limited number at a time, so a large batch takes a while to arrive, and events are not delivered in a fixed order. Compare the record's updated_at with the copy you hold and ignore an event that is older. A missed event can be recovered with ?updated_after= on the contact, company, lead, deal and task lists.

Squad handoff event

call.handoff is sent once per handoff, after it is saved, on phone and web calls alike. A subscription scoped to one agent receives it when that agent is the one the call was handed to.

data fieldMeaning
session_idThe voice session
call_idThe phone call, or null for a web or API session
squad_idThe squad the call runs in
from_bot_id, from_roleThe member that handed the call over
to_bot_id, to_roleThe member that has the call now
reasonThe handing agent's one-line summary of what the caller needs. Empty when the agent or your workspace keeps no voice content (zero data retention)
handoff_number1 for the call's first handoff, then 2, …
atWhen the handoff happened (ISO 8601)

Post-call analysis event

voice_analysis.completed is sent once per call, after the post-call analysis is saved. It carries the whole result, so a survey or feedback agent's answers reach your system without a second request.

data fieldMeaning
analysis_idThe analysis record
session_idThe voice session the analysis belongs to
bot_idThe agent that took the call
summaryA short summary of the call, or null
sentimentpositive, neutral, negative or unknown
dispositionThe call outcome label, or null
goal_mettrue / false for the agent's goal variable, null when the agent declares none
extractedThe agent's own analysis variables by name, for example {"rating": 4, "callback_requested": false}; {} when it declares none

Voice session end reasons

A voice session fires exactly one of voice_session.ended or voice_session.failed, once, whichever way it ends: the agent or caller hanging up, a DELETE, the managed voice agent socket closing, or the session timing out. The event is sent only after the end has been saved. If two end signals arrive at the same moment, the first one decides end_reason and duration_seconds, and the later one changes nothing.

end_reasonSession statusEvent
agent_error, start_failed, and the managed voice agent's start-up errors (invalid_settings, concurrency_limit, model_unavailable, non_settings_message_before_settings)failedvoice_session.failed
timeout (ran past its maximum duration and nothing reported the end), token_expired (never connected)timeoutvoice_session.failed
Any other reason, for example caller_hangup, participant_disconnect, client_disconnect, agent_closed, max_duration, no_input, handoff, transferred, budget_exhausted, api_deletecompletedvoice_session.ended

Delivery format

Every event is a POST with this JSON body:

{
  "event": "message.received",
  "data": { "conversation_id": "c0ffee00-1111-2222-3333-444455556666", "channel": "web", "from": "chat-session-id", "text": "Hi" },
  "timestamp": "2026-08-04T09:12:00.512301+00:00"
}

and these headers:

Content-Type: application/json
X-CallMissed-Event: message.received
X-CallMissed-Delivery: <delivery id>
X-CallMissed-Signature: sha256=<hex digest>
X-CallMissed-Signature-Previous: sha256=<hex digest>   (only for 24 hours after a secret rotation)

X-CallMissed-Delivery is the id you see in the delivery log; use it to de-duplicate, because a retry or a replay can deliver the same event more than once.

A response with a status below 300 counts as delivered. Anything else, or no response within 10 seconds, is retried: up to 5 attempts in total, waiting 2, 4, 8 and 16 seconds between them. The delivery log records the attempt count, the last status code and the last error.

A Slack Incoming Webhook URL (https://hooks.slack.com/services/...) receives the event formatted as Slack message blocks instead of the JSON body above.

Signing and verification

Every delivery, including the test delivery, carries the X-CallMissed-Signature header above.

The digest is HMAC-SHA256(secret, raw_request_body). Compute it over the raw bytes you received, before any JSON parsing, and compare with a constant-time function.

import hashlib, hmac

def verify(raw_body: bytes, headers: dict, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return any(
        hmac.compare_digest(expected, headers.get(name, ""))
        for name in ("X-CallMissed-Signature", "X-CallMissed-Signature-Previous")
    )

The full secret is returned only once, in the POST create response (and, for a new secret, in the rotate-secret response). Every later read masks it as first4 + "****" + last4. Store it when you create the subscription.

Rotating the secret

POST /api/v1/webhooks/{webhook_id}/rotate-secret replaces the secret. From then on X-CallMissed-Signature is signed with the new secret, and for 24 hours every delivery also carries X-CallMissed-Signature-Previous, signed with the old one. A receiver that accepts either header (as in the snippet above) keeps verifying while you deploy the new secret. After 24 hours only the new secret signs. Rotating again during the window replaces the old secret with the one just retired.

URL rules

The url is validated on create, on update, before a test delivery, and on every real delivery attempt. Endpoints resolving to private, loopback, link-local, or shared address space are rejected. Use a public HTTPS URL.


GET/api/v1/webhooks

Lists your tenant's subscriptions, newest first.

ParameterTypeRequiredConstraints
limitintegerNo1 <= limit <= 200, default 50
curl https://api.callmissed.com/api/v1/webhooks \
  -H "Authorization: Bearer cm_your_api_key"
[
  {
    "id": "w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
    "tenant_id": "a0b1c2d3-4455-6677-8899-aabbccddeeff",
    "url": "https://hooks.acme.com/callmissed",
    "secret": "Xk4p****9dQz",
    "events": ["conversation.started", "message.received"],
    "is_active": true,
    "bot_id": null,
    "created_at": "2026-07-19T08:00:00Z"
  }
]

403 when a cm_ key lacks webhooks:write, or a JWT caller is not owner/admin; 422 when limit is outside 1 .. 200.

POST/api/v1/webhooks

Creates a subscription and generates its secret. Returns 201.

FieldTypeRequiredConstraints
urlstringYes1-2048 chars. Must pass the URL rules above
eventsstring[]Yes1-50 entries, each from the event table
bot_idUUID | nullNoScope the subscription to one agent. Omit for a workspace-wide subscription. CRM record events reach workspace-wide subscriptions only
curl -X POST https://api.callmissed.com/api/v1/webhooks \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.acme.com/callmissed",
    "events": ["conversation.started", "message.received", "payment.succeeded"],
    "bot_id": null
  }'
{
  "id": "w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "tenant_id": "a0b1c2d3-4455-6677-8899-aabbccddeeff",
  "url": "https://hooks.acme.com/callmissed",
  "secret": "Xk4pR7tYb2Lm8sNcVhJ3wQeZ1aFgD6uO9dQz",
  "events": ["conversation.started", "message.received", "payment.succeeded"],
  "is_active": true,
  "bot_id": null,
  "created_at": "2026-08-04T10:40:00Z"
}

This response is the only place the full secret appears.

StatusCause
400The URL failed validation
403Key missing webhooks:write, key missing the read scope for a CRM record event in events, or JWT caller is not owner/admin
404Agent not found when bot_id is not an agent in your tenant
422Unknown event type, empty events, or url over 2048 chars

PUT/api/v1/webhooks/{webhook_id}

Partial update. Every field is optional; omitted fields are unchanged. Returns the subscription with a masked secret.

FieldTypeRequiredConstraints
urlstring | nullNo1-2048 chars. Re-validated when present
eventsstring[] | nullNoReplaces the whole list. An empty array [] subscribes to every event except the CRM record events, which are sent only when named
is_activeboolean | nullNoPause or resume deliveries
bot_idUUID | nullNoRe-scope to an agent in your tenant
clear_bot_idbooleanNoDefault false. Send true to widen a scoped subscription back to the whole workspace. Takes precedence over bot_id
curl -X PUT https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8 \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"events": ["message.received"], "is_active": false}'

404 Webhook not found; 404 Agent not found for a foreign bot_id; 403, 400, and 422 as for create.

DELETE/api/v1/webhooks/{webhook_id}

Returns 204 with an empty body. Writes a webhook.delete audit event.

curl -X DELETE https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8 \
  -H "Authorization: Bearer cm_your_api_key"

403 for insufficient permission; 404 when the subscription is not in your tenant.

POST/api/v1/webhooks/{webhook_id}/rotate-secret

Generates a new signing secret and returns it once. No request body. The previous secret keeps signing X-CallMissed-Signature-Previous until previous_secret_expires_at (24 hours), see Rotating the secret. Writes a webhook.secret.rotate audit event.

curl -X POST https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/rotate-secret \
  -H "Authorization: Bearer cm_your_api_key"
{
  "id": "w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "tenant_id": "a0b1c2d3-4455-6677-8899-aabbccddeeff",
  "url": "https://hooks.acme.com/callmissed",
  "secret": "Qm7tZ2pLw9XcV4bN1sRkY8eH3uJ6dF0aGq5o",
  "events": ["conversation.started", "message.received"],
  "is_active": true,
  "bot_id": null,
  "created_at": "2026-07-19T08:00:00Z",
  "previous_secret_expires_at": "2026-10-18T09:30:00+00:00"
}

403 when a cm_ key lacks webhooks:write, or a JWT caller is not owner/admin; 404 when the subscription is not in your tenant.

POST/api/v1/webhooks/{webhook_id}/test

Sends a real signed POST to the configured URL and reports the result. No request body. The stored URL is re-validated first, so a hostname repointed at a private address after creation is rejected.

The delivered payload:

{
  "event": "test",
  "timestamp": "2026-08-04T10:45:12.004921+00:00",
  "data": { "message": "This is a test webhook delivery from CallMissed" }
}
curl -X POST https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/test \
  -H "Authorization: Bearer cm_your_api_key"
{
  "success": true,
  "status_code": 200,
  "latency_ms": 214,
  "error": null
}

success is true only for a 2xx from your endpoint. On a network failure the response is still 200 with success: false, status_code: null, and a short error such as Connection failed or Request timed out. The 10-second request timeout applies. The test is not retried and is not written to the delivery log.

403 for insufficient permission; 404 when the subscription is not in your tenant.

GET/api/v1/webhooks/{webhook_id}/deliveries

Delivery log for one subscription, newest first.

ParameterTypeRequiredConstraints
limitintegerNo1 <= limit <= 200, default 50
curl "https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/deliveries?limit=50" \
  -H "Authorization: Bearer cm_your_api_key"
[
  {
    "id": "d5e6f708-1920-4a3b-8c4d-5e6f708192a3",
    "webhook_id": "w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
    "event": "message.received",
    "status_code": 500,
    "attempts": 3,
    "success": false,
    "error": "HTTP 500",
    "created_at": "2026-08-04T09:12:00Z",
    "delivered_at": null
  }
]

status_code and error are null when not applicable; delivered_at is null until a delivery succeeds. The payload body is not in this list response - fetch one delivery for that.

403 when a cm_ key lacks webhooks:write; 404 when the subscription is not in your tenant; 422 when limit is outside 1 .. 200.

GET/api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}

Full inspector view of one delivery, including the stored payload.

curl https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/deliveries/d5e6f708-1920-4a3b-8c4d-5e6f708192a3 \
  -H "Authorization: Bearer cm_your_api_key"
{
  "id": "d5e6f708-1920-4a3b-8c4d-5e6f708192a3",
  "webhook_id": "w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "event": "message.received",
  "status_code": 500,
  "attempts": 3,
  "success": false,
  "error": "HTTP 500",
  "payload": {
    "event": "message.received",
    "data": { "conversation_id": "c0ffee00-1111-2222-3333-444455556666", "role": "user" }
  },
  "created_at": "2026-08-04T09:12:00+00:00",
  "delivered_at": null
}
StatusCause
403Key missing webhooks:write, or JWT caller is not owner/admin
404Webhook not found or Delivery not found
422Either path id is not a valid UUID

POST/api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/replay

Re-sends a past delivery's payload against the subscription's current URL and secret. No request body. A new delivery row is created; the original is preserved. Returns 202.

curl -X POST https://api.callmissed.com/api/v1/webhooks/w1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/deliveries/d5e6f708-1920-4a3b-8c4d-5e6f708192a3/replay \
  -H "Authorization: Bearer cm_your_api_key"
{
  "delivery_id": "a7b8c9d0-e1f2-4304-8516-27a8b9c0d1e2",
  "status": "queued"
}

status: "queued" means the replay was accepted, not that it succeeded. Poll the deliveries list for the new row's outcome. Writes a webhook.delivery.replay audit event.

StatusCause
400Webhook is inactive - re-enable it with PUT first
403Key missing webhooks:write, or JWT caller is not owner/admin
404Webhook not found or Delivery not found

On this page