Already Have an Account? Sign In β€Ί
✨ New: delivery log, replay and test events

Real-Time iMessage Events

Signed webhooks for every step of a conversation. See every delivery we made, replay any of them, and test every event before you go live.

Sending a test event, opening the delivery log and replaying a failed delivery in Tuco

See, replay and test every delivery

Debug an integration without guessing what we sent.

Delivery log

Every request we sent to your endpoint in the last 30 days: status, latency, retries, the exact body and your endpoint's response.

One-click replay

Fixed your endpoint? Re-send any delivery. It goes to the webhook's current URL, signed with the current secret, marked X-Tuco-Replay.

Test any event

Send a realistic test for every event type and variant: text, photo, PDF, link, voice note, P2P SMS, failures and a heartbeat.

Exactly once

Each event fires once per webhook. Our single automatic retry reuses the same X-Tuco-Delivery-Id, so a slow endpoint can drop it.

Edit in place

Change the URL, events or Authorization header, pause with the Active switch, or rotate the signing secret.

All in the API

Deliveries, replay, test and secret rotation are public endpoints, so anything the dashboard does, your API key can do.

11 event types

Subscribe to the ones you need, per webhook.

πŸ“€

message.sent

A message was sent. Fires once per message. The channel field says whether it went as iMessage or as SMS from your own line.

πŸ’¬

message.reply

The lead replied, including photos, files and voice notes.

❌

message.failed

A message could not be sent after its retries, or expired before it could go out.

πŸ›Ÿ

message.fallback

The recipient has no iMessage and the text went through your fallback SMS provider.

πŸ‘οΈ

message.opened

Read receipt, when the recipient has them on.

❀️

message.reaction

The lead reacted (tapback) to a message you sent.

πŸ€–

message.ai_draft

The AI copilot drafted a reply for review.

βœ…

message.ai_draft_approved

A draft was approved and sent, from any channel.

🚫

message.ai_draft_rejected

A draft was rejected, from any channel.

πŸ™‹

conversation.handover

The AI agent handed the conversation to a person and stopped replying.

πŸŽ™οΈ

call.recording.ready

A call recording is stored, with a signed download link. Once per call.

Example payload

A message.sent body, shortened. Full payloads for every event β†’

{
  "event": "message.sent",
  "timestamp": "2026-03-12T22:57:03.000Z",
  "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG",
  "messageId": "69b344bc6dae1d942ece4d0e",
  "channel": "imessage",
  "message": {
    "_id": "69b344bc6dae1d942ece4d0e",
    "message": "Here's your document.",
    "messageType": "imessage",
    "status": "sent",
    "fromLineId": "69ab427ac1feb77d7f46462e",
    "recipientPhone": "+919876543210",
    "recipientName": "Jane Doe",
    "leadId": "69b2c41d352a78479d2c623b",
    "sentAt": "2026-03-12T22:57:02.892Z"
  },
  "leadId": "69b2c41d352a78479d2c623b",
  "lead": { "firstName": "Jane", "phone": "+919876543210", "source": "gohighlevel" },
  "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R",
  "ghlLocationId": "eL7DD22BdZ0rismu7qCA",
  "data": {}
}

Headers and signature

X-Tuco-SignatureHMAC-SHA256 hex digest of the body, signed with your webhook secret
X-Tuco-EventEvent type, e.g. message.sent
X-Tuco-Event-IdStable id of the event. Same on a retry and on a replay
X-Tuco-Delivery-IdId of this delivery. Same on the automatic retry, new on a replay
X-Tuco-Replaytrue when re-sent with Replay
X-Tuco-Testtrue when sent as a test (the body also has testMode: true)
const crypto = require('crypto');

// Verify against the raw body exactly as received.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.TUCO_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const signature = req.get('x-tuco-signature') || '';

  if (signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const { event, messageId } = JSON.parse(req.body);
  res.status(200).send('OK'); // answer within 10 seconds
});

Ready to Build with Webhooks?

Add an endpoint, send a test event, and watch it land in the delivery log.