# CommSync Webhooks — Agent Reference # Fetch this document to understand how to receive real-time CommSync events. ## What this is and why it exists CommSync webhooks are push-based event delivery. When a customer sends your user an SMS or email, CommSync POSTs a signed JSON payload to a URL you register. This is the chatbot trigger. Webhooks exist to replace MCP polling. Cron-ing list_threads every few minutes to ask "anything new?" is expensive: every poll burns tokens for nothing 99% of the time. With webhooks, your agent sleeps until a real event fires — and the payload itself usually contains enough context (thread, person, labels, last N messages in verbose mode) to decide whether to reply without round-tripping back to MCP. Use both surfaces together: - WEBHOOKS for "wake me when something happens" (this document). - MCP for "do something now" — send the reply, look up a contact, label a thread. See https://commsync.ai/docs/mcp.txt for the MCP tool catalog. ## Connection Endpoint: a URL on YOUR side that CommSync will POST to. Method: HTTP POST Body: application/json Header: X-CommSync-Signature: t=,v1= (two v1= parts for 24h after a secret rotation — accept either) Required response: HTTP 2xx within 10 seconds. Non-2xx or timeout → retry. ## Bootstrap (three steps from zero to receiving events) 1. Mint a CommSync API key (format csk_<48-hex>) in Settings → API Keys. 2. Register a webhook endpoint via MCP (recommended — no UI needed): POST https://server.commsync.ai/api/mcp Authorization: Bearer csk_ Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "register_webhook", "arguments": { "url": "https://your-agent.example.com/commsync", "events": ["message.received"], "mode": "verbose", "messageHistoryCount": 20 } } } Response data contains { "endpoint": { ... }, "secret": "<32-byte hex>" }. The secret is shown ONCE. Store it (env var / secrets manager). Use it to verify every incoming signature. Lose it → rotate_webhook_secret. 3. Start receiving. Every event that matches your subscription will hit your URL until you call update_webhook { status: "disabled" } or delete_webhook. ## Envelope Every POST body looks like this: { "id": "evt_<32 hex chars>", // unique per delivery — your dedup key "type": "message.received", "createdAt": "2026-05-21T09:30:00.000Z", "endpointId": "", "mode": "concise" | "verbose", "data": { ...event-specific... } } ## Event catalog (12 events) ### message.received Fires when: inbound SMS or email finished ingestion and was persisted. data (concise): thread: { id, subject, lastMessageAt, messageCount } person: { id, displayName, source } | null // source "USER" (saved) or "AUTO" (added automatically) labels: [ "Sales", "VIP", ... ] // user-defined label names message: id, threadId, channel ("SMS"|"EMAIL"), direction ("INBOUND"|"OUTBOUND"), status, body, createdAt, sentAt, fromIdentity: { value, kind ("PHONE"|"EMAIL") }, toIdentity: { value, kind } data (verbose adds): thread.recentMessages: [ serializedMessage, ... ] // up to messageHistoryCount person.identities: [ { id, kind, value, displayName }, ... ] attachments: [ { id, filename, mimeType, sizeBytes, url } ] // url is a pre-signed S3 GET valid for 1 hour emailHeaders: // only for EMAIL channel { messageId, inReplyTo, references, listUnsubscribe, authentication: { spf, dkim, dmarc } } labelConfidence: { "": <0..1>, ... } Sample: https://commsync.ai/docs/webhooks/samples/message.received.concise.json https://commsync.ai/docs/webhooks/samples/message.received.verbose.json ### message.sent Fires when: an outbound message was successfully handed to the carrier (SMS) or the SMTP server (email) — i.e. the moment it leaves QUEUED. Resulting status is SENT for email and Twilio, but DELIVERED for Skyetel/JustCall (no delivery callback — optimistically marked delivered on handoff). data: identical shape to message.received (message.direction is "OUTBOUND"). message.received + message.sent together give you both halves of a conversation without subscribing to message.status_changed, which also carries every downstream delivery-status flip. Sample: https://commsync.ai/docs/webhooks/samples/message.sent.concise.json ### message.status_changed Fires when: a Message.status flip is recorded. (QUEUED→SENT, SENT→DELIVERED, SENT→FAILED, …) data (concise): same as message.received PLUS: previousStatus: "" | null currentStatus: "" data (verbose): same verbose additions as message.received. Sample: https://commsync.ai/docs/webhooks/samples/message.status_changed.concise.json ### thread.created Fires when: a new Thread row is inserted (first message from a previously unknown conversation partner). data (concise): thread: { id, subject, lastMessageAt, messageCount } person: { id, displayName, source } | null // null id = a handle with no contact; source "AUTO" = added automatically labels: [] // usually empty at thread birth message: serializedMessage // the message that created the thread ORDER IS NOT GUARANTEED: CommSync emits thread.created before message.received for the same message, but the two are dispatched and retried independently and can arrive in either order. Do not assume you have already seen the thread when message.received lands — both payloads carry the full thread object. Sample: https://commsync.ai/docs/webhooks/samples/thread.created.concise.json ### email.opened Fires when: a tracked outbound email records a distinct open — the recipient's mail client fetched the read-receipt image. Only emails sent with read receipts on carry the image (Message.trackOpens, resolved at send time from the composer toggle and the sender's settings). Untracked emails never fire this event. data (concise): same as message.received (message.direction is "OUTBOUND") PLUS: open: { firstOpenedAt, // ISO timestamp of the first recorded open lastOpenedAt, // ISO timestamp of this open openCount } // distinct opens so far; 1 = the first open data (verbose): same verbose additions as message.received. open is a snapshot taken at the open that produced the event. Filter on open.openCount === 1 if you only care about the first open. Dedup and filtering happen BEFORE the event exists: refetches within 60 seconds count as the same view (no event), opens in the first seconds after the send are treated as relay-side scanners (no event), and known security-gateway user agents are dropped (no event). An absent event is NOT proof the email went unread — many mail clients block remote images. Sample: https://commsync.ai/docs/webhooks/samples/email.opened.concise.json ### attachment.extracted Fires when: an attachment's text layer finished extraction (PDF text, image OCR, office doc, or .ics calendar parse) and is now searchable. IMPORTANT: message.received fires BEFORE the attachment bytes are fetched or OCR'd. If your integration reads documents, act on this event, not on message.received. data (concise): the message.received envelope PLUS: attachment: { id, filename, mimeType, sizeBytes, messageId, textLength, // characters extracted hasText, // textLength > 0 extractedAt } calendarEvents: [ { id, uid, method, status, summary, startsAt, endsAt, organizerEmail, attendeeEmails } ] // non-empty only for .ics / text/calendar attachments The extracted text itself is NOT included (it can be megabytes). Fetch it with the read_attachment MCP tool using attachment.id. Attempt-once: an attachment that fails extraction is stamped and never retried, so this event fires at most once per attachment. ### message.entities_extracted Fires when: CommSync read structured items out of an inbound message or one of its PDFs: a bill, an invoice, a receipt, a subscription event, a shipment, a reservation, a deadline, a phone number, an address, or a person. At most one event per extraction run. data (concise and verbose are the same): thread: { id, subject } message: { id, threadId, channel, direction, sentAt } // no body entities: [ { id, kind, subtype, payload, amountMinor, // minor units (cents) as a string, or null currency, dueAt, occursAt, settled, // { byEntityId, at } when a receipt paid it attachmentId, source, aiFields } ] A security entity (a password reset, a new sign-in, a connected app) is NEVER sent. A message with only security entities sends no event. Sample: https://commsync.ai/docs/webhooks/samples/message.entities_extracted.concise.json ### contact.merged Fires when: two or more contacts are merged into one. data (concise): contact: { id, displayName, identities: [ { id, kind, value, displayName } ] } mergedContactIds: [ "", ... ] // these ids NO LONGER EXIST If you store CommSync contact ids, remap mergedContactIds onto contact.id here. This is the only notification you get — the merged-away rows are deleted. Not channel-scopable: a contact isn't tied to a line, so endpoints scoped to specific channels do not receive this event (scoped endpoints fail closed). ### email_account.health_changed Fires when: a mailbox stops syncing (status "unhealthy") or starts working again (status "recovered"). data (concise): emailAccount: { id, emailAddress, isActive, lastSyncedAt } health: { status: "unhealthy" | "recovered", errorKind: "AUTH" | "RATE_LIMIT" | "NETWORK" | ... | null, error: "" | null, since: "" | null } Edge-triggered: fires ONCE on the transition in each direction, not on every failed retry. A mailbox that stays broken produces exactly one event. An expired-credential mailbox fails silently — nothing looks wrong from the inbox — so this is the event to alert on. errorKind "AUTH" means a human has to re-authenticate the account. Channel-scopable: the mailbox IS the channel, so a scoped endpoint receives this only for mailboxes within its own scope. ### agent_turn.awaiting_approval Fires when: a DRAFT-mode CommSync Agent drafted a reply that needs human approval before it can be sent. data (concise): the thread envelope PLUS: agentTurn: { id, status, threadId, messageId, createdAt, agent: { id, name, mode } } No "message" block — nothing has been sent yet. The draft body lives on the AgentTurn; read it via the agents API. In verbose mode this event gets thread.recentMessages[] and person.identities[] but NOT attachments[] or emailHeaders, which derive from a message anchor it does not carry. Approve or reject via the agents API. Without this event the approval queue is poll-only. ### agent_turn.sent Fires when: an agent sent a reply to a contact (AUTO/SUPERVISED modes, or an approved DRAFT turn). data (concise): same shape as agent_turn.awaiting_approval; agentTurn.messageId points at the Message the agent sent. This is the oversight trail — every message an AI sent under your org's name. ### agent_conversation.analyzed Fires when: CommSync analyzed one ended agent conversation. It judged the goals of the agents, captured their fields, and wrote a title, a summary, and the mood. A re-run of the analysis fires it again. data (concise): conversation: { id, threadIds, agentIds, agents: [ { id, name } ], channels: [ "SMS" | "EMAIL" ], // both when SMS and email joined startedAt, endedAt, outcome: "ANSWERED" | "HANDED_TO_PERSON" | "NO_REPLY_NEEDED" | "CONTACT_STOPPED" | "UNFINISHED", counts: { contactMessages, agentReplies, turns, toolCalls, toolErrors, escalations, heldBySafety, rejectedDrafts, approvedDrafts }, editRate, // 0 to 1, draft-first only, else null firstReplySeconds, medianReplySeconds, takenOver, optedOut, costUsd } analysis: { analyzedAt, title, summary, mood: "POSITIVE" | "NEUTRAL" | "NEGATIVE" | null, frustration, // 0 to 100, or null successScore, // 0 to 100, or null with no goal goals: [ { key, name, result: "MET" | "NOT_MET" | "UNKNOWN" | "NOT_APPLICABLE", score, // 1 to 5 for a scored goal, else null reason } ], fields: [ { key, name, type, value } ] } A field value has the type of its field: text, a number, true or false, a date ("2026-05-21"), a date and time ("2026-05-21T10:00"), one of the choices, an email address, a phone number in E.164, { amount, currency }, or a list of text. Null means the conversation did not give it. A person's correction replaces the judge's answer. A field marked sensitive is NEVER sent. The event carries no message text and no evidence quotes; the message events carry the text. Audience: each user with authority over EVERY thread of the conversation (a conversation can hold an SMS thread and an email thread). A channel-scoped endpoint receives it only when its scope holds every line of those threads. Sample: https://commsync.ai/docs/webhooks/samples/agent_conversation.analyzed.concise.json ## Signature verification Header format: X-CommSync-Signature: t=,v1=[,v1=] Algorithm: HMAC-SHA256(secret, ".") Tolerance: reject if |now − t| > 300 seconds (clock skew defense) Compare with: timing-safe equal (constant-time) Match rule: accept when ANY v1= part matches your secret. For 24h after a rotation the header carries two v1= parts: previous secret first, current secret LAST. CRITICAL: verify against the RAW request body, BEFORE any JSON parsing or middleware that mutates the bytes. Whitespace changes will break the HMAC. ### Node / TypeScript import { createHmac, timingSafeEqual } from 'crypto'; export function verify(secret, rawBody, header, toleranceSec = 300) { const pairs = header.split(',').map(p => p.split('=')); const t = Number(pairs.find(([k]) => k === 't')?.[1]); const signatures = pairs.filter(([k]) => k === 'v1').map(([, v]) => v); if (!Number.isFinite(t) || signatures.length === 0) return false; if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; const expected = createHmac('sha256', secret) .update(`${t}.${rawBody}`).digest(); return signatures.some(sig => { const b = Buffer.from(sig, 'hex'); return b.length === expected.length && timingSafeEqual(expected, b); }); } ### Python import hmac, hashlib, time def verify(secret: str, raw_body: bytes, header: str, tolerance_sec: int = 300) -> bool: pairs = [p.split("=", 1) for p in header.split(",") if "=" in p] signatures = [v for k, v in pairs if k == "v1"] try: t = int(next(v for k, v in pairs if k == "t")) except (StopIteration, ValueError): return False if abs(time.time() - t) > tolerance_sec: return False signed = f"{t}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, sig) for sig in signatures) ### Go func Verify(secret, rawBody, header string, toleranceSec int64) bool { ts := "" var signatures []string for _, p := range strings.Split(header, ",") { kv := strings.SplitN(p, "=", 2) if len(kv) != 2 { continue } if kv[0] == "t" { ts = kv[1] } if kv[0] == "v1" { signatures = append(signatures, kv[1]) } } t, err := strconv.ParseInt(ts, 10, 64) if err != nil { return false } now := time.Now().Unix() diff := now - t; if diff < 0 { diff = -diff } if diff > toleranceSec { return false } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(fmt.Sprintf("%d.%s", t, rawBody))) expected := hex.EncodeToString(mac.Sum(nil)) for _, sig := range signatures { if hmac.Equal([]byte(expected), []byte(sig)) { return true } } return false } ### Secret rotation grace window When you call rotate_webhook_secret, the previous secret stays valid for 24h. For those 24h every request carries two v1= signatures: the PREVIOUS secret's first, the CURRENT secret's last. A receiver that accepts any matching v1= part (the samples above) keeps passing while you deploy the new secret. A receiver that reads only the last v1= part checks the current secret, so it needs the new secret at once. After 24h only the new secret signs. A second rotation inside the window makes the secret it retires the previous one; the older secret stops at once. ## Delivery semantics Timeout per attempt: 10 seconds Success criterion: HTTP 2xx Retry schedule: 1 min → 5 min → 30 min → 2 h → 12 h (5 attempts max) Auto-disable: 100 consecutive failures OR 24h continuous failure → endpoint flips to status="disabled" → re-enable via update_webhook { status: "active" } → that also resets the consecutive-failure counter Idempotency key: event.id (format: evt_<32 hex chars>) Same id is never delivered twice for the same delivery row. Retries reuse the id. resend_webhook_delivery creates a NEW row with a fresh id. Response body: truncated to 2 KB in the delivery log; we still consider a 2xx status a success regardless of body. Log retention: delivered rows are deleted after 30 days; failed, dead, and pending rows after 90 days. A deleted row is gone from list_webhook_deliveries and cannot be resent. ## What fires and what does not - Hidden lines still fire. Endpoints follow the lines you have ACCESS to, not the lines in your own inbox. Hiding a line from your inbox does not stop its events. Use channelScope to stop them. - History imports fire nothing. A first mailbox sync, a history backfill, and a phone history import add old messages with no events. Only messages that arrive live fire message.received / message.sent. - Calls and voicemails fire nothing. The events cover messages only. ## Tier caps STARTER: 1 endpoint per user PRO: 3 endpoints per user POWER: 10 endpoints per user Per-org override available via admin-grant. ## Channel scoping By default an endpoint receives events from ALL channels — every connected line (email account / phone number), including lines connected later. You can restrict any endpoint to specific lines via the channelScope field on register_webhook / update_webhook: "channelScope": { "allChannels": false, "channels": [ { "channelType": "EMAIL_ACCOUNT", "channelId": "" }, { "channelType": "PHONE_NUMBER", "channelId": "" } ] } Semantics: - allChannels: true (default when omitted) → all lines, auto-includes future lines. - allChannels: false → fixed allowlist; events whose thread lives on a non-listed channel are filtered out BEFORE delivery (never reach you). A thread's lines are the line it started on plus every line that carried a copy (an email thread a teammate's mailbox also received). A match on any of them delivers. Must list at least 1 channel. Lines connected later are NOT auto-added. - Deleted lines fail closed: their scope entries simply stop matching. - Channel ids: list_email_accounts / list_phone_numbers via MCP. - Pass channelScope on update_webhook to replace the scope wholesale. ## Security & guardrails - HTTPS required in production. http:// is accepted only in dev. - SSRF blocked: private (RFC-1918), loopback, link-local, unique-local, multicast, and broadcast hosts are rejected at registration AND at send time (DNS rebinding defense). - Events are scoped to userId. You only receive your own user's events. - Best practice: store secrets in a secrets manager; redact event.id and request bodies if you log them (payloads contain customer message text). ## MCP tools for managing webhooks (call via https://server.commsync.ai/api/mcp) list_webhooks Read No params. get_webhook Read endpointId register_webhook Write url, events[], mode?, messageHistoryCount?, channelScope? Returns { endpoint, secret } — secret shown ONCE. update_webhook Write endpointId, url?, events?, mode?, messageHistoryCount?, status?, channelScope? rotate_webhook_secret Write endpointId Old secret valid 24h; returns new secret ONCE. delete_webhook Destr endpointId — irreversible. list_webhook_deliveries Read endpointId, cursor? 25 rows/page, newest first. resend_webhook_delivery Write deliveryId — new evt_* id, fresh delivery row. ## Common workflows 1. Chatbot reply loop (the canonical use case): register_webhook(url, ["message.received"], mode: "verbose") ↓ POST arrives, verify signature ↓ inspect data.message + data.thread.recentMessages ↓ decide reply (LLM call) ↓ MCP send_sms({ threadId, identityId, smsBody }) done — no polling, no token waste. 2. Delivery-monitoring bot: register_webhook(url, ["message.status_changed"]) ↓ branch on data.currentStatus - "FAILED" → page on-call, log to incident system - "DELIVERED" → close the loop in your outbound-message tracker 3. Label-driven router: register_webhook(url, ["message.received"], mode: "verbose") ↓ inspect data.labels and/or data.labelConfidence ↓ route to the right downstream system (Sales / Support / Spam-bin) 4. CRM-sync bot: register_webhook(url, ["thread.created"]) ↓ create matching CRM record from data.person + data.labels ↓ link CRM id back via MCP update_contact { notes: "crm:..." } ## Pointers Machine spec (JSON): https://commsync.ai/docs/webhooks.json Payload fixtures: https://commsync.ai/docs/webhooks/samples/..json e.g. /docs/webhooks/samples/message.received.verbose.json MCP tool catalog: https://commsync.ai/docs/mcp.txt Human page: https://commsync.ai/docs/webhooks