Message Webhooks

Overview

Message webhooks push status updates to a URL you control whenever a message reaches a terminal state. Configure them in your workspace settings — Tuco handles delivery automatically.

Webhook calls are POST requests with a JSON body. All events share the same base fields; each event type adds its own specific fields. Outgoing message events are fired when a message is sent (accepted by Tuco), not when delivery is confirmed on the recipient’s device.

Test before you go live. Send a test delivery for any event and variant — it is built by the same code as a live delivery, so if your parser handles the test it handles production. Every delivery (test or live) is in the delivery log with the exact body sent and your response, and any one can be replayed. The same tools are in the dashboard under Integrations → Webhooks.

Event types

Event	When	Payload `message` type	Status field
`message.sent`	Message was successfully sent (accepted by Tuco)	Object (full message doc)	`"sent"`
`message.failed`	Message failed after all retries (technical error)	Object (full message doc)	`"failed"`
`message.fallback`	Recipient has no iMessage; primary channel unavailable	Object (full message doc)	`"fallback"`
`message.opened`	Recipient opened/read the message (read receipt; when supported)	Object (full message doc with `readAt`)	—
`message.reply`	A lead or contact replied to a message you sent	String (reply text only)	—
`message.reaction`	A lead reacted to one of your messages	Object (reaction event payload)	—
`message.ai_draft`	AI copilot drafted a reply for review	String (draft text only)	—
`message.ai_draft_approved`	Draft approved & sent (any channel: dashboard, Telegram, unibox, API)	String (draft text only)	—
`message.ai_draft_rejected`	Draft rejected (any channel)	String (draft text only)	—
`conversation.handover`	The AI SDR handed the conversation to a human and stopped replying	— (see `data.handover`)	—
`call.recording.ready`	A call’s recording is stored and downloadable (once per call)	— (see `data`)	—
`dnc.added`	A contact was added to your Do-Not-Contact list — they replied STOP (iMessage or SMS), or you added them via the dashboard or `POST /api/dnc` (once per entry)	— (see `data.dnc`)	—

`message.ai_draft` — review AI drafts from your own tools

When your knowledge base runs in Copilot mode, every AI-drafted reply fires message.ai_draft before anything is sent. The payload carries the draft text on message (string) and a data.replyId handle:

{
  "event": "message.ai_draft",
  "timestamp": "2026-03-12T21:20:02.114Z",
  "workspaceId": "org_abc123",
  "leadId": "69b2c41d352a78479d2c623b",
  "lead": { "firstName": "Jane", "lastName": "Doe", "phone": "+15551230001" },
  "message": "Sure — the onboarding call runs about 30 minutes. Thursday 2pm work?",
  "data": {
    "replyId": "69b330a1cad37b94a846ef01",
    "draftMessage": "Sure — the onboarding call runs about 30 minutes. Thursday 2pm work?",
    "conversationRecipient": "+15551230001",
    "inboundText": "How long is the onboarding call?",
    "confidence": 0.92,
    "mode": "copilot",
    "approveEndpoint": "/api/knowledge-base/auto-replies"
  }
}

Approve (sends the draft) or reject it with your API key:

curl -X POST https://app.tuco.ai/api/knowledge-base/auto-replies \
  -H "Authorization: Bearer tuco_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "replyId": "69b330a1cad37b94a846ef01", "action": "approve" }'

action is approve (claims the draft and sends it), reject, or mark_sent (claim only — you already delivered the text yourself). The claim is atomic and first-action-wins across every channel, so an approval from Telegram, the dashboard, and your API call can never double-send. A 409 response means another channel already actioned the draft. Every resolution then fires message.ai_draft_approved or message.ai_draft_rejected — regardless of which channel actioned it — with data.approvalChannel (dashboard, api, telegram, telegram_edit, telegram_retry, unibox_direct_send) so your workflow can log who approved what, including approvals that never touched your tools.

`message.reply`

Sent when a new reply from a lead or contact is recorded. Use it to update your CRM, trigger automations, or log conversations.

When a contact owner is set (contactOwnerEmail), reply email notifications are routed only to the contact owner rather than all workspace users.

Payload shape: Top-level flat fields; data.reply is identical to one item in GET /api/replies (same keys, same types). Reply text is top-level message (string). parentMessages is always present (array; possibly empty).

Top-level fields

Field	Description
`event`	`"message.reply"`
`timestamp`	When the webhook was sent (ISO UTC)
`workspaceId`	Workspace that owns the conversation
`messageId`	ID of the reply message (the one they sent)
`leadId`	Lead ID when the reply is linked to a lead. Omitted if no lead could be matched.
`firstName`	Lead first name (when lead is present). Backward-compat flat field.
`lastName`	Lead last name (when lead is present). Backward-compat flat field.
`phone`	Lead phone (when lead is present). Backward-compat flat field.
`listId`	Lead list ID (when lead is present). Backward-compat flat field.
`fromLineId`	Line ID that received the reply. Backward-compat flat field.
`recipientName`	Display name (lead name or recipient). Backward-compat flat field.
`repliedAtUtc`	When the reply was received (UTC ISO 8601). Always present.
`parentMessages`	Last 2 outbound messages you sent to this lead. Always present (array; empty if none). Same shape as GET /api/replies.
`message`	Reply text only (string) — what they replied with.
`attachmentDownloadUrls`	Present only when the lead’s reply included a photo/file. Public, signed, 30-day URLs — `GET` each one (no auth header) to download the image/file bytes with the correct `Content-Type`. Omitted for text-only replies.
`attachmentNames`	Filenames aligned 1:1 with `attachmentDownloadUrls` (e.g. `["IMG_1380.jpeg"]`). Omitted for text-only replies.
`attachmentUrls`	Raw private-storage URLs for reference. These return `403` on their own — use `attachmentDownloadUrls` to fetch the bytes.
`originalMessageId`	ID of the message they replied to (when known)
`originalMessage`	Original outbound message object (when known)
`lead`	Full lead object when available. Omitted if no lead could be matched.

`message` (reply text only)

For message.reply, message is the reply text only (string) — what the lead or contact replied with.

`data.reply` — matches GET /api/replies item exactly

data.reply has the exact same shape as one element of GET /api/replies replies array:

Field	Description
`leadId`	Lead ID (string)
`messageId`	Reply message ID
`respondedAtUtc`	When the reply was received (UTC ISO)
`recipientEmail`	Recipient email or undefined
`recipientPhone`	Recipient phone or undefined
`name`	Display name (lead name or recipient)
`attachmentDownloadUrls`	Signed, fetchable download URLs for the latest reply’s attachments (only when it had any).
`attachmentNames`	Filenames aligned 1:1 with `attachmentDownloadUrls`.
`parentMessages`	Array of `{ messageId, message, sentAtUtc, batchId, stepIndex }` (same as API)
`recentReplies`	Array of `{ messageId, message, receivedAtUtc, attachmentDownloadUrls?, attachmentNames? }` — last 10 inbound replies (same as API)

Plus recentReplies — the last 10 inbound replies from this lead (array, possibly empty):

Field	Description
`messageId`	Reply message ID
`message`	Reply text
`receivedAtUtc`	When the reply was received (UTC ISO)
`attachmentDownloadUrls`	Signed, fetchable download URLs — present only on replies that carried attachments.
`attachmentNames`	Filenames aligned 1:1 with `attachmentDownloadUrls`.

Example payload:

{
  "event": "message.reply",
  "timestamp": "2025-03-02T15:00:00.000Z",
  "workspaceId": "org_xxx",
  "messageId": "674abc...",
  "leadId": "667f1f77bcf86cd799439012",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+12025551234",
  "listId": "674list...",
  "fromLineId": "699f704bc405fae6ca299a08",
  "recipientName": "Jane Doe",
  "repliedAtUtc": "2025-03-02T14:59:58.000Z",
  "parentMessages": [
    { "messageId": "674def...", "message": "Hi Jane, we have an offer...", "sentAtUtc": "2025-03-01T10:00:00.000Z", "batchId": null, "stepIndex": null }
  ],
  "message": "Thanks, I'm interested!",
  "data": {
    "reply": {
      "leadId": "667f1f77bcf86cd799439012",
      "messageId": "674abc...",
      "respondedAtUtc": "2025-03-02T14:59:58.000Z",
      "recipientEmail": "jane@example.com",
      "recipientPhone": null,
      "name": "Jane Doe",
      "parentMessages": [
        { "messageId": "674def...", "message": "Hi Jane, we have an offer...", "sentAtUtc": "2025-03-01T10:00:00.000Z", "batchId": null, "stepIndex": null }
      ],
      "recentReplies": [
        { "messageId": "674abc...", "message": "Thanks, I'm interested!", "receivedAtUtc": "2025-03-02T14:59:58.000Z" }
      ]
    },
    "repliedAtUtc": "2025-03-02T14:59:58.000Z",
    "parentMessages": [ { "messageId": "674def...", "message": "Hi Jane, we have an offer...", "sentAtUtc": "2025-03-01T10:00:00.000Z", "batchId": null, "stepIndex": null } ]
  },
  "originalMessageId": "674def...",
  "lead": { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com" }
}

Reply with a photo/file

When the lead replies with an image or file, the same payload additionally carries attachmentDownloadUrls + attachmentNames (top-level and inside data.reply / its recentReplies). GET a download URL to store the bytes — no Authorization header needed, the signature is the capability:

{
  "event": "message.reply",
  "workspaceId": "org_xxx",
  "messageId": "674abc...",
  "message": "here's the damage on my car",
  "attachmentDownloadUrls": [
    "https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=aHR0cHM...&exp=1786752000000&sig=Vh9k..."
  ],
  "attachmentNames": ["IMG_1380.jpeg"],
  "attachmentUrls": ["https://abc.private.blob.vercel-storage.com/workspaces/org_xxx/attachments/2996...-IMG_1380.jpeg"],
  "data": {
    "reply": {
      "leadId": "667f1f77bcf86cd799439012",
      "messageId": "674abc...",
      "respondedAtUtc": "2025-03-02T14:59:58.000Z",
      "attachmentDownloadUrls": ["https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=...&exp=...&sig=..."],
      "attachmentNames": ["IMG_1380.jpeg"],
      "recentReplies": [
        { "messageId": "674abc...", "message": "here's the damage on my car", "receivedAtUtc": "2025-03-02T14:59:58.000Z",
          "attachmentDownloadUrls": ["https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=...&exp=...&sig=..."],
          "attachmentNames": ["IMG_1380.jpeg"] }
      ]
    }
  }
}

Multiple attachments per reply. A single reply can carry many photos/files — attachmentDownloadUrls and attachmentNames are parallel arrays with one entry per attachment (there is no longer a 2-attachment cap; the full set is captured).Large bursts arrive progressively. When a lead sends a big batch (e.g. 20 photos), the first few are attached to the message.reply webhook right away and the rest are ingested in the background — the underlying iMessage server hands each attachment over slowly, so a large burst takes a couple of minutes to finish. The webhook is not re-sent as the remainder land, so to get the complete set for a messageId, call GET /api/replies a minute or two after the reply.

Each attachmentDownloadUrls link is a signed, 30-day capability to read that one file. Fetch and store the bytes in your own system rather than persisting the URL. Need a fresh link later? Call GET /api/replies or wait for the next message.reply.

`message.sent`

Sent when a message has been sent (accepted by Tuco). This is the only outgoing-message event fired to your webhook; Tuco does not fire a separate event when delivery is confirmed on the recipient’s device. Payload: The message field is the full message object (not a string), with _id, message, messageType, status, fromLineId, recipientPhone, recipientEmail, recipientName, leadId, workspaceId, createdByUserId, sentAt, createdAt, updatedAt, etc. Top-level also includes leadId, lead (full lead when available), and integration IDs.

Full example body

{
  "event": "message.sent",
  "timestamp": "2026-03-12T22:57:03.000Z",
  "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG",
  "messageId": "69b344bc6dae1d942ece4d0e",
  "message": {
    "_id": "69b344bc6dae1d942ece4d0e",
    "message": "Here's your document.",
    "messageType": "imessage",
    "status": "sent",
    "fromLineId": "69ab427ac1feb77d7f46462e",
    "recipientPhone": "+919876543210",
    "recipientEmail": "jane@example.com",
    "recipientName": "Jane Doe",
    "leadId": "69b2c41d352a78479d2c623b",
    "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG",
    "createdByUserId": "user_3AZrxEi8CR2uMq9simYrwcJpfsL",
    "sentAt": "2026-03-12T22:57:02.892Z",
    "createdAt": "2026-03-12T22:57:00.856Z",
    "updatedAt": "2026-03-12T22:57:02.892Z"
  },
  "leadId": "69b2c41d352a78479d2c623b",
  "lead": { "_id": "69b2c41d352a78479d2c623b", "firstName": "Jane", "lastName": "Real", "email": "jane@example.com", "phone": "+919876543210", "listId": "69ab444ac1feb77d7f46462f", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG", "source": "gohighlevel" },
  "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R",
  "ghlLocationId": "eL7DD22BdZ0rismu7qCA",
  "hsPortalId": null,
  "hsContactId": null,
  "channel": "imessage",
  "data": {}
}

string

"message.sent"

string

How the message actually left: imessage, p2p_sms, email, or call. See P2P SMS.

string

Tuco message ID

object

Full message document (not string)

string

Lead ID when known

object

Full lead when available

string | null

GHL contact ID for integrations

string | null

GHL location ID for integrations

string

When the webhook was fired (ISO UTC)

message.sent fires exactly once per message, whichever way the send was confirmed.

P2P SMS (green bubble from your line)

When a line has P2P SMS on and the recipient isn’t on iMessage, the line’s paired iPhone sends a regular SMS from the line’s own number. That is a successful send by your line, so you get message.sent with "channel": "p2p_sms", and no message.fallback. The message object keeps messageType: "imessage" (what was requested) and carries smsForwarded: true, so read channel rather than messageType to know how it actually went out. Abbreviated: only the fields that differ from the full example above are shown.

{
  "event": "message.sent",
  "messageId": "69b344bc6dae1d942ece4d0e",
  "message": {
    "_id": "69b344bc6dae1d942ece4d0e",
    "messageType": "imessage",
    "status": "sent",
    "smsForwarded": true,
    "smsForwardedMethod": "apple-script"
  },
  "channel": "p2p_sms"
}

P2P SMS is different from fallback. Fallback (message.fallback) means the message went out through your workspace’s fallback provider (Twilio, GoHighLevel, or your own fallback webhook) from a different number. A message never produces both.

`message.reaction`

Sent when a lead or contact reacts to an existing message in a conversation. Tuco treats reactions differently from replies:

they are stored as reactions on the original message
they do not become a normal text reply
they do not trigger AI reply handling

Top-level fields

Field	Description
`event`	`"message.reaction"`
`timestamp`	When the webhook was sent (ISO UTC)
`workspaceId`	Workspace that owns the conversation
`messageId`	The original message id that received the reaction, when Tuco can match it
`leadId`	Lead id when the conversation is linked to a lead
`firstName`	Lead first name when available
`lastName`	Lead last name when available
`phone`	Lead phone when available
`fromLineId`	The line that received the reaction
`recipientName`	Lead or contact display name
`message`	The raw reaction text emitted by the upstream channel
`data.reaction`	Normalized reaction type such as `love`, `like`, `dislike`, `laugh`, `emphasize`, or `question`
`data.reactedAtUtc`	When Tuco recorded the reaction
`data.reactionMessageId`	Upstream reaction message id when available

Example payload

{
  "event": "message.reaction",
  "timestamp": "2026-05-18T16:30:00.000Z",
  "workspaceId": "org_xxx",
  "messageId": "6a07878bafb1789f8fcb68e6",
  "leadId": "667f1f77bcf86cd799439012",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+12025551234",
  "fromLineId": "699f704bc405fae6ca299a08",
  "recipientName": "Jane Doe",
  "message": "Loved “Looks good to me”",
  "data": {
    "reaction": "love",
    "reactedAtUtc": "2026-05-18T16:29:58.000Z",
    "reactionMessageId": "BB-123"
  }
}

`message.failed`

Sent once when a message definitely did not go out:

Case	`message.errorMessage`
The message waited for a line that was down longer than the queue window (24 hours) and expired	`Line unavailable for longer than the 24h queue window — message not sent`
Sending failed twice in a row with an error from the device	the error, e.g. `Request failed with status code 502`

message.failed is not sent when delivery simply could not be confirmed (the message may still have arrived — check the conversation), or when Tuco declines to send a message (for example a link or attachment in the very first message to a new contact). The message field is the full message object, including errorMessage, failureReason (line_down_expired or transient_exhausted) and failureClass. data.error repeats the reason.

Full example body

{
  "event": "message.failed",
  "timestamp": "2026-10-15T22:40:43.117Z",
  "workspaceId": "org_xxx",
  "leadId": "7e57ab1e0000000000000001",
  "messageId": "7e57ab1e0000000000000002",
  "message": {
    "_id": "7e57ab1e0000000000000002",
    "message": "This is a test webhook from Tuco. If you see this, your endpoint is working correctly.",
    "messageType": "imessage",
    "direction": "sent",
    "recipientPhone": "+15551234567",
    "recipientName": "Test Contact",
    "fromLineId": "7e57ab1e0000000000000003",
    "fromLinePhone": "+15557654321",
    "fromLineEmail": "line@example.com",
    "leadId": "7e57ab1e0000000000000001",
    "source": "api",
    "workspaceId": "org_xxx",
    "createdByUserId": "user_test",
    "status": "failed",
    "externalMessageId": "TEST-0000-0000-0000-000000000001",
    "createdAt": "2026-10-15T22:40:43.116Z",
    "updatedAt": "2026-10-15T22:40:43.116Z",
    "errorMessage": "Line unavailable for longer than the 24h queue window \u2014 message not sent",
    "failureReason": "line_down_expired",
    "failureClass": "permanent"
  },
  "contactOwnerEmail": null,
  "ghlContactId": null,
  "ghlLocationId": null,
  "hsPortalId": null,
  "hsContactId": null,
  "data": {
    "error": "Line unavailable for longer than the 24h queue window \u2014 message not sent"
  }
}

string

"message.failed"

object

Full message document (includes errorMessage)

string

Human-readable explanation of the failure

Tuco does not send an SMS because of message.failed. To retry another way, do it from your workflow when this event arrives. (Recipients without iMessage are a different case: see message.fallback.)

`message.fallback`

Sent when Tuco determines that the primary channel (e.g. iMessage) is not available for this recipient. This is a business outcome, not a technical failure. The message field is the full message object. data includes reason and optionally checkedAddresses (string[]).

Full example body

{
  "event": "message.fallback",
  "timestamp": "2026-03-12T22:42:23.000Z",
  "workspaceId": "org_xxx",
  "messageId": "69b3414e6dae1d942ece4d0d",
  "message": {
    "_id": "69b3414e6dae1d942ece4d0d",
    "message": "Hi from N8N - mar 13",
    "messageType": "imessage",
    "status": "fallback",
    "recipientPhone": "+919876543211",
    "recipientName": "Usha Giridhar",
    "leadId": "69b3414e6dae1d942ece4d0c",
    "workspaceId": "org_xxx",
    "errorMessage": "Prospect's iMessage not available on +919876543211",
    "createdAt": "2026-03-12T22:42:22.379Z",
    "updatedAt": "2026-03-12T22:42:22.962Z"
  },
  "leadId": "69b3414e6dae1d942ece4d0c",
  "lead": { "_id": "69b3414e6dae1d942ece4d0c", "firstName": "Usha", "lastName": "Giridhar", "phone": "+919876543211" },
  "ghlContactId": "8LUvKi8KL6oPnjHuUeAG",
  "ghlLocationId": "eL7DD22BdZ0rismu7qCA",
  "hsPortalId": null,
  "hsContactId": null,
  "data": {
    "reason": "Prospect's iMessage not available on +919876543211",
    "checkedAddresses": ["+919876543211"]
  }
}

string

"message.fallback"

object

Full message document (status fallback)

string

Human-readable explanation

string[]

All addresses Tuco checked for iMessage availability before deciding fallback. Useful for debugging and auditing.

Common patterns

Auto-send SMS

Trigger an SMS via your own Twilio/fallback when you receive message.fallback. Or enable Tuco’s built-in fallback SMS on the workspace.

Tag lead in CRM

Flag the lead as “no iMessage” so future sends pick the right channel automatically.

`message.opened`

Sent when the recipient has opened/read the message (read receipt). Fired where the channel supports read receipts. Use it to track engagement or trigger follow-ups. Payload: Same top-level shape as message.sent. The message field is the full message object (not a string), including readAt (ISO 8601 UTC) when the message was read. data may include readAt.

Full example body

{
  "event": "message.opened",
  "timestamp": "2026-03-13T10:00:00.000Z",
  "workspaceId": "org_xxx",
  "messageId": "69b344bc6dae1d942ece4d0e",
  "message": {
    "_id": "69b344bc6dae1d942ece4d0e",
    "message": "Here's your document.",
    "messageType": "imessage",
    "status": "sent",
    "fromLineId": "69ab427ac1feb77d7f46462e",
    "recipientPhone": "+919876543210",
    "recipientEmail": "jane@example.com",
    "recipientName": "Jane Doe",
    "leadId": "69b2c41d352a78479d2c623b",
    "workspaceId": "org_xxx",
    "createdByUserId": "user_xxx",
    "sentAt": "2026-03-12T22:57:02.892Z",
    "readAt": "2026-03-13T10:00:00.000Z",
    "createdAt": "2026-03-12T22:57:00.856Z",
    "updatedAt": "2026-03-13T10:00:00.000Z"
  },
  "leadId": "69b2c41d352a78479d2c623b",
  "lead": { "_id": "69b2c41d352a78479d2c623b", "firstName": "Jane", "lastName": "Real", "email": "jane@example.com", "phone": "+919876543210" },
  "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R",
  "ghlLocationId": "eL7DD22BdZ0rismu7qCA",
  "hsPortalId": null,
  "hsContactId": null,
  "data": { "readAt": "2026-03-13T10:00:00.000Z" }
}

string

"message.opened"

object

Full message document including readAt (ISO UTC when read)

string

When the message was opened (ISO UTC)

`conversation.handover`

Fires once when the AI SDR decides a conversation needs a person and stops replying to it. This is the event to wire to your routing, your inbox or your on-call rota — it is the only signal that a lead is waiting on a human.

The AI is already paused when this fires (data.handover.aiPaused is always true). Nothing further is sent on that conversation until a person takes it.

Payload shape

{
  "event": "conversation.handover",
  "timestamp": "2026-10-06T09:14:02.118Z",
  "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG",
  "leadId": "69b2c41d352a78479d2c623b",
  "contactOwnerEmail": "rep@yourcompany.com",
  "data": {
    "handover": {
      "recipient": "+13025550123",
      "trigger": "pricing_question",
      "reason": "Lead asked for custom enterprise pricing, which the bot may not quote.",
      "confidence": 0.92,
      "inboundText": "what would this cost for 40 seats?",
      "withheldDraft": "Great question — let me get you exact numbers.",
      "contactOwnerEmail": "rep@yourcompany.com",
      "handedOverAt": "2026-10-06T09:14:02.090Z",
      "aiPaused": true
    }
  }
}

`data.handover`

string

The contact the conversation is with — phone in E.164, or email.

string

What tripped the handover, e.g. a rule name or detected intent.

string

Plain-English explanation of why the bot stopped. Safe to show a rep.

number

Model confidence in the handover decision, 0–1. Omitted when not scored.

string

The lead’s message that triggered it. Omitted when there is none.

string

What the AI would have said, held back. Hand this to whoever picks the conversation up so the lead does not have to repeat themselves. Omitted when there was no draft.

string

Owner of the contact, for routing. Also present at the top level.

string

ISO 8601 timestamp of the handover.

boolean

Always true. The AI has stopped replying to this conversation.

leadId and contactOwnerEmail are also lifted to the top level so you can route on owner without reaching into data.handover. They are omitted when unknown.

Shared fields (all events)

Every webhook payload includes these base fields:

Field	Description
`event`	Event type: `message.sent`, `message.failed`, `message.fallback`, `message.opened`, or `message.reply`
`timestamp`	When the webhook was sent (ISO UTC)
`workspaceId`	Your workspace ID
`messageId`	Tuco message ID — use as your primary key (for reply, this is the reply message ID)
`message`	For sent/failed/fallback/opened: full message object. For reply: string (reply text only)
`leadId`	Lead involved (when known)
`lead`	Full lead object when available
`contactOwnerEmail`	Email of the workspace user assigned as contact owner for this lead. May be `null` for legacy leads.
`ghlContactId`, `ghlLocationId`, `hsPortalId`, `hsContactId`	Integration IDs (nullable)
`data`	Event-specific data (e.g. `reason`, `checkedAddresses` for fallback; `reply`, `repliedAtUtc`, `parentMessages` for reply; `readAt` for opened)

`call.recording.ready`

Sent once per call, when the call’s recording has been stored. Use data.recordingDownloadUrl to fetch the audio: it is a signed, public link valid for 30 days and needs no Authorization header. data.recordingUrl is the raw storage location and is not fetchable with an API key.

Full example body

{
  "event": "call.recording.ready",
  "timestamp": "2026-10-15T21:39:55.737Z",
  "workspaceId": "org_xxx",
  "leadId": "7e57ab1e0000000000000001",
  "lead": {
    "_id": "7e57ab1e0000000000000001",
    "firstName": "Test",
    "lastName": "Contact",
    "email": "test.contact@example.com",
    "phone": "+15551234567",
    "companyName": "Test Co",
    "listId": "7e57ab1e0000000000000004",
    "workspaceId": "org_xxx",
    "source": "api",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "contactOwnerEmail": null,
  "ghlContactId": null,
  "ghlLocationId": null,
  "hsPortalId": null,
  "hsContactId": null,
  "data": {
    "ghlContactId": null,
    "ghlLocationId": null,
    "hsPortalId": null,
    "hsContactId": null,
    "callId": "7e57ab1e0000000000000007",
    "lineId": "7e57ab1e0000000000000003",
    "surface": "unibox",
    "from": "+15557654321",
    "to": "+15551234567",
    "callStatus": "billed",
    "requestedAt": "2026-10-15T21:39:55.736Z",
    "answeredAt": "2026-10-15T21:39:55.736Z",
    "endedAt": "2026-10-15T21:39:55.736Z",
    "durationSec": 42,
    "hangupCause": "normal_clearing",
    "recordingUrl": "https://example.private.blob.vercel-storage.com/tuco-test/recordings/call.mp3",
    "recordingDownloadUrl": "https://app.tuco.ai/api/attachments/crm-media/call.mp3?u=aHR0cHM6Ly9leGFtcGxlLnByaXZhdGUuYmxvYi52ZXJjZWwtc3RvcmFnZS5jb20vdHVjby10ZXN0L3JlY29yZGluZ3MvY2FsbC5tcDM&exp=1794692395737&sig=yvnwFVMl3XL2jNcmtg7iNtC5XkYuvBesCggEQMzjAr8",
    "recordingName": "call.mp3"
  }
}

string

Tuco call id.

string

Number the call was placed from (your line), E.164.

string

Number that was called, E.164.

number | null

Talk time in seconds.

string | null

Call status when the recording was stored, e.g. billed.

string

Signed link that streams the audio (30 days).

string

File name, e.g. call.mp3.

`dnc.added`

Sent once per new Do-Not-Contact entry. Use it to stop the same person on your other channels (WhatsApp, email, dialer) the moment they opt out of iMessage. It fires when:

a contact replies with an opt-out keyword (STOP, UNSUBSCRIBE, OPT OUT, REMOVE ME, DO NOT CONTACT) on iMessage, or a carrier keyword (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) to your Telnyx or Twilio fallback number
someone adds a contact in the dashboard, or you call POST /api/dnc

A second STOP from someone already on the list does not fire again. Bulk CSV and list imports, and DNC mirrored in from GoHighLevel or HubSpot, do not fire — read those with GET /api/dnc?since=. The reply itself still arrives as message.reply with optedOut: true. Try it without waiting for a real opt-out:

curl -X POST "https://app.tuco.ai/api/webhooks/<webhookId>/test" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "event": "dnc.added", "variant": "opt_out" }'

Variants: opt_out (replied STOP) and manual (added via the dashboard or API).

Full example body

{
  "event": "dnc.added",
  "timestamp": "2026-10-19T11:22:49.694Z",
  "workspaceId": "org_xxx",
  "leadId": "7e57ab1e0000000000000001",
  "contactOwnerEmail": null,
  "ghlContactId": null,
  "ghlLocationId": null,
  "hsPortalId": null,
  "hsContactId": null,
  "optedOut": true,
  "data": {
    "ghlContactId": null,
    "ghlLocationId": null,
    "hsPortalId": null,
    "hsContactId": null,
    "optedOut": true,
    "dnc": {
      "id": "7e57ab1e0000000000000008",
      "phone": "+15551234567",
      "email": null,
      "reason": "opt-out",
      "source": "keyword-STOP",
      "addedBy": "system",
      "addedAt": "2026-10-19T11:22:49.693Z",
      "keyword": "stop"
    }
  }
}

string

DNC entry id. Same id GET /api/dnc returns, so you can dedupe across the webhook and polling.

string | null

Phone number, E.164.

string | null

Email address, lower case.

string

opt-out for a reply, otherwise the reason given when it was added (default manual).

string

keyword-<WORD> for a reply (e.g. keyword-STOP), api for POST /api/dnc with an API key, manual-ui for the dashboard.

string

The opt-out text they sent. Only present for replies.

string

When the entry was added (ISO 8601, UTC).

Headers & signature verification

Every webhook POST includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Tuco-Signature`	HMAC-SHA256 hex digest of the JSON body, signed with your webhook secret
`X-Tuco-Event`	Event type (e.g. `message.sent`)
`X-Tuco-Timestamp`	ISO 8601 UTC timestamp of when the webhook was fired
`X-Tuco-Event-Id`	Stable id of the logical event (`evt_…`). The same on a retry and on a replay.
`X-Tuco-Delivery-Id`	Id of this delivery to this endpoint (`dlv_…`). The same on Tuco’s automatic retry; new on a replay.
`X-Tuco-Replay`	`true` when the delivery was re-sent with the Replay endpoint or button.
`X-Tuco-Test`	`true` when sent by the test endpoint. The body also carries `"testMode": true`.
`Authorization`	Only when you configured a custom Authorization header on the webhook; sent verbatim.

Delivery guarantees

Each event fires once per webhook. message.sent fires once per message, whichever way the send was confirmed; message.reply once per inbound message; message.failed, message.fallback, message.opened, message.reaction and the message.ai_draft* events once per message, reaction or draft.
If your endpoint does not answer 2xx within 10 seconds, Tuco retries once after 5 seconds with the same X-Tuco-Delivery-Id. If your endpoint already processed the first attempt (it was just slow), drop the retry by that id.
Every delivery is kept for 30 days in the delivery log, with the exact body sent and your endpoint’s response.

Verify the signature against the raw request body exactly as received. Re-serializing a parsed body can change it and make a valid signature fail.

Verify signatures to confirm webhooks actually came from Tuco:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your handler:
const sig = req.headers['x-tuco-signature'];
if (!verifyWebhook(req.body, sig, process.env.TUCO_WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature');
}

import hmac, hashlib, json

def verify_webhook(body: dict, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        json.dumps(body, separators=(',', ':')).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Your webhook secret is shown once when you create the webhook. Save it immediately. It can’t be retrieved later. If you lose it, rotate the secret to get a new one.

Consuming webhooks safely

Use messageId + event as your key

Make updates idempotent. If you’ve already processed a (messageId, event) pair, ignore duplicates.

Move status forward only

Only update your local status in the forward direction (for example sent after queued). Never move backwards.

Return 200 quickly

Tuco expects a 2xx response within a few seconds. Do heavy processing asynchronously after acknowledging the webhook.

Log workspaceId and leadId

These fields let you trace events back to the right tenant and contact in multi-workspace setups.

Tuco does not retry webhook delivery. Each event fires once (fire-and-forget). If your endpoint is down or returns a non-2xx status, that delivery is lost. Make sure your endpoint is reliable and returns 2xx quickly. You can use the health-check endpoint to verify your endpoint is reachable.

​Overview

​Event types

​message.ai_draft — review AI drafts from your own tools

​message.reply

​Top-level fields

​message (reply text only)

​data.reply — matches GET /api/replies item exactly

​Reply with a photo/file

​message.sent

​Full example body

​P2P SMS (green bubble from your line)

​message.reaction

​Top-level fields

​Example payload

​message.failed

​Full example body

​message.fallback

​Full example body

​Common patterns

Auto-send SMS

Tag lead in CRM

​message.opened

​Full example body

​conversation.handover

​data.handover

​Shared fields (all events)

​call.recording.ready

​Full example body

​dnc.added

​Full example body

​Headers & signature verification

​Delivery guarantees

​Consuming webhooks safely

Overview

Event types

`message.ai_draft` — review AI drafts from your own tools

`message.reply`

Top-level fields

`message` (reply text only)

`data.reply` — matches GET /api/replies item exactly

Reply with a photo/file

`message.sent`

Full example body

P2P SMS (green bubble from your line)

`message.reaction`

Top-level fields

Example payload

`message.failed`

Full example body

`message.fallback`

Full example body

Common patterns

`message.opened`

Full example body

`conversation.handover`

`data.handover`

Shared fields (all events)

`call.recording.ready`

Full example body

`dnc.added`

Full example body

Headers & signature verification

Delivery guarantees

Consuming webhooks safely