{ "version": "1", "generatedAt": "2026-08-25T12:14:06.123Z", "$comment": "Machine-readable spec for CommSync outbound webhooks. Companion to /docs/webhooks.txt (prose) and /docs/webhooks/samples/* (fixtures).", "envelope": { "type": "object", "required": [ "id", "type", "createdAt", "endpointId", "mode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Unique per delivery. Use as your dedup key." }, "type": { "type": "string", "enum": [ "message.received", "message.sent", "message.status_changed", "thread.created", "email.opened", "attachment.extracted", "contact.merged", "email_account.health_changed", "agent_turn.awaiting_approval", "agent_turn.sent" ] }, "createdAt": { "type": "string", "format": "date-time" }, "endpointId": { "type": "string" }, "mode": { "type": "string", "enum": [ "concise", "verbose" ] }, "data": { "type": "object" } } }, "events": { "message.received": { "fires": "Inbound SMS or email finished ingestion and was persisted.", "modes": [ "concise", "verbose" ], "data": { "concise": { "type": "object", "required": [ "thread", "person", "labels", "message" ], "properties": { "thread": { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, "person": { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } } } }, "verbose": { "type": "object", "description": "Concise shape, with additions: thread.recentMessages[], person.identities[], attachments[], emailHeaders, labelConfidence.", "properties": { "thread": { "allOf": [ { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, { "type": "object", "properties": { "recentMessages": { "type": "array", "items": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } }, "description": "Recent messages on the thread, oldest first, length up to messageHistoryCount." } } } ] }, "person": { "allOf": [ { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "value" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] }, "value": { "type": "string" }, "displayName": { "type": [ "string", "null" ] } } } } } } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "id", "filename", "mimeType", "sizeBytes", "url" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid for 1 hour. Null if the asset was skipped." } } } }, "emailHeaders": { "oneOf": [ { "type": "object", "properties": { "messageId": { "type": [ "string", "null" ] }, "inReplyTo": { "type": [ "string", "null" ] }, "references": { "type": [ "array", "null" ], "items": { "type": "string" } }, "listUnsubscribe": { "type": [ "string", "null" ] }, "authentication": { "type": "object", "properties": { "spf": { "type": [ "string", "null" ] }, "dkim": { "type": [ "string", "null" ] }, "dmarc": { "type": [ "string", "null" ] } } } } }, { "type": "null" } ], "description": "Present on EMAIL-channel messages only. Null for SMS." }, "labelConfidence": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "AI label name → confidence score, from AiLabelAssignment rows." } } } }, "sampleUrls": [ "/docs/webhooks/samples/message.received.concise.json", "/docs/webhooks/samples/message.received.verbose.json" ] }, "message.sent": { "fires": "An outbound message was handed to the carrier (SMS) or SMTP server (email) — the moment it leaves QUEUED. The resulting status is SENT for email and Twilio, but DELIVERED for Skyetel/JustCall, which have no delivery callback and are optimistically marked delivered on handoff. Pair with message.received to mirror both halves of a conversation without the delivery-status churn of message.status_changed.", "modes": [ "concise", "verbose" ], "data": { "concise": { "$ref": "#/events/message.received/data/concise" }, "verbose": { "$ref": "#/events/message.received/data/verbose" } }, "sampleUrls": [ "/docs/webhooks/samples/message.sent.concise.json" ] }, "message.status_changed": { "fires": "A Message.status flip is recorded (QUEUED→SENT, SENT→DELIVERED, SENT→FAILED, …).", "modes": [ "concise", "verbose" ], "data": { "concise": { "type": "object", "required": [ "thread", "person", "labels", "message", "previousStatus", "currentStatus" ], "properties": { "thread": { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, "person": { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } }, "previousStatus": { "type": [ "string", "null" ] }, "currentStatus": { "type": [ "string", "null" ] } } }, "verbose": { "$ref": "#/events/message.received/data/verbose" } }, "sampleUrls": [ "/docs/webhooks/samples/message.status_changed.concise.json", "/docs/webhooks/samples/message.status_changed.verbose.json" ] }, "thread.created": { "fires": "A new Thread row is inserted (first message from a previously-unknown conversation partner). Emitted before message.received for the same message, but the two are dispatched and retried independently so arrival order is NOT guaranteed.", "modes": [ "concise", "verbose" ], "data": { "concise": { "type": "object", "required": [ "thread", "person", "labels", "message" ], "properties": { "thread": { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, "person": { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } } } }, "verbose": { "type": "object", "properties": { "thread": { "allOf": [ { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, { "type": "object", "properties": { "recentMessages": { "type": "array", "items": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } }, "description": "Recent messages on the thread, oldest first, length up to messageHistoryCount." } } } ] }, "person": { "allOf": [ { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "value" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] }, "value": { "type": "string" }, "displayName": { "type": [ "string", "null" ] } } } } } } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } } } } }, "sampleUrls": [ "/docs/webhooks/samples/thread.created.concise.json", "/docs/webhooks/samples/thread.created.verbose.json" ] }, "email.opened": { "fires": "A tracked outbound email recorded a distinct open — the recipient fetched the read-receipt image. Fires only for emails sent with read receipts on (Message.trackOpens). Refetches within 60s count as the same view and do not fire; opens in the first seconds after the send and known security-scanner user agents are filtered before the event exists. An absent event is NOT proof the email went unread — many mail clients block remote images.", "modes": [ "concise", "verbose" ], "notes": "data.open is a snapshot taken at the open that produced the event. Filter on open.openCount === 1 for first-open-only handling. Dedup key stays event.id — each distinct open is its own event.", "data": { "concise": { "type": "object", "required": [ "thread", "person", "labels", "message", "open" ], "properties": { "thread": { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, "person": { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } }, "open": { "type": "object", "required": [ "firstOpenedAt", "lastOpenedAt", "openCount" ], "properties": { "firstOpenedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastOpenedAt": { "type": [ "string", "null" ], "format": "date-time" }, "openCount": { "type": "integer", "description": "Distinct opens so far. 1 = the first open." } } } } }, "verbose": { "$ref": "#/events/message.received/data/verbose" } }, "sampleUrls": [ "/docs/webhooks/samples/email.opened.concise.json" ] }, "attachment.extracted": { "fires": "An attachment's text layer finished extraction (PDF text, image OCR, office doc, or .ics parse) and is now searchable. Act on this rather than message.received when your integration reads documents — message.received fires before the bytes are fetched or OCR'd. Attempt-once: fires at most once per attachment.", "modes": [ "concise", "verbose" ], "data": { "concise": { "type": "object", "required": [ "thread", "person", "labels", "message", "attachment", "calendarEvents" ], "properties": { "thread": { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, "person": { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message": { "type": "object", "required": [ "id", "threadId", "channel", "direction", "status", "body", "createdAt", "sentAt", "fromIdentity", "toIdentity" ], "properties": { "id": { "type": "string" }, "threadId": { "type": "string" }, "channel": { "type": "string", "enum": [ "SMS", "EMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "fromIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } }, "toIdentity": { "type": "object", "required": [ "value", "kind" ], "properties": { "value": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] } } } } }, "attachment": { "type": [ "object", "null" ], "description": "The extracted text itself is NOT included (it can be megabytes) — fetch it with the read_attachment MCP tool.", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "messageId": { "type": [ "string", "null" ] }, "textLength": { "type": "integer" }, "hasText": { "type": "boolean" }, "extractedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "calendarEvents": { "type": "array", "description": "Non-empty only for .ics / text/calendar attachments.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "uid": { "type": "string" }, "method": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "summary": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "organizerEmail": { "type": [ "string", "null" ] }, "attendeeEmails": { "type": "array", "items": { "type": "string" } } } } } } }, "verbose": { "type": "object", "description": "Concise shape plus the standard verbose additions." } }, "sampleUrls": [ "/docs/webhooks/samples/attachment.extracted.concise.json" ] }, "contact.merged": { "fires": "Two or more contacts were merged into one. mergedContactIds no longer exist — remap any stored CommSync contact ids onto contact.id. This is the only notification; the merged-away rows are deleted.", "modes": [ "concise", "verbose" ], "channelScopable": false, "notes": "Not tied to a line, so endpoints scoped to specific channels never receive it (scoped endpoints fail closed).", "data": { "concise": { "type": "object", "required": [ "contact", "mergedContactIds" ], "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "PHONE", "EMAIL" ] }, "value": { "type": "string" }, "displayName": { "type": [ "string", "null" ] } } } } } }, "mergedContactIds": { "type": "array", "items": { "type": "string" } } } }, "verbose": { "$ref": "#/events/contact.merged/data/concise" } }, "sampleUrls": [ "/docs/webhooks/samples/contact.merged.concise.json" ] }, "email_account.health_changed": { "fires": "A mailbox stopped syncing (status \"unhealthy\") or started working again (status \"recovered\"). Edge-triggered: fires once per transition, never repeatedly while the mailbox stays broken.", "modes": [ "concise", "verbose" ], "channelScopable": true, "notes": "The mailbox IS the channel, so a scoped endpoint receives this only for mailboxes within its own scope. errorKind \"AUTH\" means a human must re-authenticate.", "data": { "concise": { "type": "object", "required": [ "emailAccount", "health" ], "properties": { "emailAccount": { "type": "object", "properties": { "id": { "type": "string" }, "emailAddress": { "type": "string" }, "isActive": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unhealthy", "recovered" ] }, "errorKind": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "since": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "verbose": { "$ref": "#/events/email_account.health_changed/data/concise" } }, "sampleUrls": [ "/docs/webhooks/samples/email_account.health_changed.concise.json" ] }, "agent_turn.awaiting_approval": { "fires": "A DRAFT-mode CommSync Agent drafted a reply that needs human approval before it can be sent.", "modes": [ "concise", "verbose" ], "notes": "No data.message — nothing has been sent yet; the draft body lives on the AgentTurn, readable via the agents API. Verbose adds thread.recentMessages[] and person.identities[] but NOT attachments[]/emailHeaders, which derive from a message anchor this event does not carry.", "data": { "concise": { "type": "object", "required": [ "thread", "person", "labels", "agentTurn" ], "properties": { "thread": { "type": "object", "required": [ "id", "subject", "lastMessageAt", "messageCount" ], "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "integer" } } }, "person": { "oneOf": [ { "type": "object", "required": [ "id", "displayName" ], "properties": { "id": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "agentTurn": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "threadId": { "type": "string" }, "messageId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "agent": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string" } } } } } } }, "verbose": { "$ref": "#/events/agent_turn.awaiting_approval/data/concise" } }, "sampleUrls": [ "/docs/webhooks/samples/agent_turn.awaiting_approval.concise.json" ] }, "agent_turn.sent": { "fires": "An agent sent a reply to a contact (AUTO/SUPERVISED, or an approved DRAFT turn). The oversight trail for messages an AI sent under your org name.", "modes": [ "concise", "verbose" ], "data": { "concise": { "$ref": "#/events/agent_turn.awaiting_approval/data/concise" }, "verbose": { "$ref": "#/events/agent_turn.awaiting_approval/data/concise" } }, "sampleUrls": [ "/docs/webhooks/samples/agent_turn.sent.concise.json" ] } }, "signing": { "algorithm": "HMAC-SHA256", "header": "X-CommSync-Signature", "format": "t=,v1=", "signedString": ".", "toleranceSeconds": 300, "compareWith": "timing-safe equal", "rawBodyNote": "Verify against the raw request body BEFORE any JSON parsing. Whitespace changes will break the HMAC.", "rotation": { "tool": "rotate_webhook_secret", "restEndpoint": "POST /api/webhooks/endpoints/:id/rotate-secret", "previousSecretGraceWindowHours": 24, "strategy": "Try the new secret first; fall back to the previous secret during rollover." } }, "delivery": { "transport": "HTTPS POST (HTTP allowed only in dev)", "timeoutSeconds": 10, "successCriterion": "HTTP 2xx response code", "retryDelaysMs": [ 60000, 300000, 1800000, 7200000, 43200000 ], "maxAttempts": 5, "autoDisable": { "consecutiveFailures": 100, "continuousFailureHours": 24, "reEnable": "update_webhook { status: \"active\" } — also resets the consecutive-failure counter" }, "idempotency": { "key": "event.id", "format": "evt_<32 hex>", "semantics": "Same id never delivered twice for the same delivery row. Retries reuse the id. resend_webhook_delivery creates a NEW row with a fresh id." }, "responseBodyTruncationChars": 2048 }, "tierCaps": { "STARTER": 1, "PRO": 3, "POWER": 10, "perOrgOverrideColumn": "Org.maxWebhookEndpointsOverride", "adminCli": "bun run admin:grant -- override --org --webhook-endpoints " }, "channelScope": { "description": "Per-endpoint channel allowlist. Default allChannels: true = events from every connected line, including lines connected later. allChannels: false restricts delivery to events whose thread lives on one of the listed channels — everything else is filtered out before delivery.", "field": "channelScope", "acceptedOn": [ "register_webhook", "update_webhook", "POST /api/webhooks/endpoints", "PATCH /api/webhooks/endpoints/:id" ], "shape": { "allChannels": "boolean (true = full access; false = use channels[])", "channels": "[{ channelType: \"EMAIL_ACCOUNT\" | \"PHONE_NUMBER\", channelId: string }] — min 1 when allChannels is false, max 1000" }, "semantics": [ "allChannels: true follows the owner’s live channel access automatically.", "allChannels: false is a fixed allowlist — lines connected later are NOT auto-added.", "Deleted lines fail closed: their scope entries stop matching and produce no events.", "update with channelScope replaces the scope wholesale.", "Channel ids come from list_email_accounts / list_phone_numbers." ], "endpointObjectFields": { "allChannels": "boolean", "channels": "[{ channelType, channelId, label, value, provider, missing }] — resolved display info; missing: true marks deleted lines" } }, "security": { "ssrfBlocks": [ "IPv4 RFC-1918 (10/8, 172.16/12, 192.168/16)", "IPv4 loopback (127/8)", "IPv4 link-local (169.254/16)", "IPv4 multicast / broadcast (224/4, 255.255.255.255)", "IPv6 loopback (::1), link-local (fe80::/10), unique-local (fc00::/7), multicast (ff00::/8)" ], "ssrfRevalidatedAtSendTime": true, "tenancy": "Endpoints are scoped per userId. Cross-user event delivery is not possible." }, "management": { "mcpTools": [ { "name": "list_webhooks", "kind": "read" }, { "name": "get_webhook", "kind": "read" }, { "name": "register_webhook", "kind": "write", "returnsSecretOnce": true }, { "name": "update_webhook", "kind": "write" }, { "name": "rotate_webhook_secret", "kind": "write", "returnsSecretOnce": true }, { "name": "delete_webhook", "kind": "destructive" }, { "name": "list_webhook_deliveries", "kind": "read" }, { "name": "resend_webhook_delivery", "kind": "write" } ], "restRoutes": [ { "method": "GET", "path": "/api/webhooks/endpoints" }, { "method": "POST", "path": "/api/webhooks/endpoints" }, { "method": "GET", "path": "/api/webhooks/endpoints/:id" }, { "method": "PATCH", "path": "/api/webhooks/endpoints/:id" }, { "method": "POST", "path": "/api/webhooks/endpoints/:id/rotate-secret" }, { "method": "DELETE", "path": "/api/webhooks/endpoints/:id" }, { "method": "GET", "path": "/api/webhooks/endpoints/:id/deliveries" }, { "method": "POST", "path": "/api/webhooks/endpoints/deliveries/:id/resend" } ] }, "links": { "human": "/docs/webhooks", "agentText": "/docs/webhooks.txt", "mcpReference": "/docs/mcp.txt", "samples": "/docs/webhooks/samples/..json" } }