Already Have an Account? Sign In ›

Webhook Setup Guide — Real-Time iMessage Events

Bharadwaj Giridhar
3 min read

Launch iMessage Brand Marketing Campaigns

Achieve measured reply rates of 15-65% across customer accounts with iMessage brand marketing. Step-by-step setup, campaign examples, and ROI benchmarks.

Webhook Setup Guide — Real-Time iMessage Events for Your Stack

Webhooks let you react to iMessage events in real time. When a message is sent, a lead replies, or a delivery fails, Tuco sends a signed POST request to your endpoint.

Supported Events

EventWhen It Fires
message.sentiMessage successfully delivered
message.failedDelivery failed (recipient may not have iMessage)
message.fallbackiMessage unavailable — Tuco sends P2P SMS from the line when it's on, or you can route the text yourself
message.replyLead replied to your message
message.openedEmail message was opened (email lines only)

CRM to iMessage in minutes

Send from your existing tools. No 10DLC, no content hashing. Better deliverability for iOS.

Setting Up a Webhook

  1. Go to API Keys → Webhooks tab in your dashboard
  2. Click Add Webhook
  3. Enter your endpoint URL (e.g., https://your-app.com/api/tuco-webhook)
  4. Copy the generated webhook secret — you'll need it to verify signatures

Verifying Signatures

Every webhook payload is signed with HMAC-SHA256 using your webhook secret. Always verify the signature before processing:

const crypto = require('crypto');

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

// In your handler:
app.post('/api/tuco-webhook', (req, res) => {
  const sig = req.headers['x-tuco-signature'];
  if (!verifyWebhook(req.body, sig, process.env.TUCO_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event, data } = req.body;
  
  switch (event) {
    case 'message.reply':
      // Lead replied — update your CRM, notify your team
      console.log(`Reply from ${data.recipientPhone}: ${data.message}`);
      break;
    case 'message.fallback':
      // iMessage unavailable — Tuco sends P2P SMS from the line when it's on; route it yourself otherwise
      sendSMS(data.recipientPhone, data.message);
      break;
  }
  
  res.status(200).send('ok');
});

Testing Your Webhook

Click the Test button next to any webhook in the dashboard. Tuco sends a test payload (with testMode: true) to your endpoint and shows you the response status code and latency.

The test payload has the same structure and HMAC signature as real events — use it to verify your endpoint works before going live.

Payload Structure

{
  "event": "message.reply",
  "timestamp": "2026-04-15T12:00:00Z",
  "workspaceId": "org_abc123",
  "data": {
    "messageId": "msg_xyz789",
    "recipientPhone": "+19042956129",
    "message": "Yes, I'm interested! Can you tell me more?",
    "status": "received",
    "lineId": "line_001",
    "firstName": "Jane",
    "lastName": "Smith",
    "attachmentUrls": [],
    "attachmentNames": []
  }
}

Headers

HeaderValue
X-Tuco-SignatureHMAC-SHA256 hex digest
X-Tuco-EventEvent type (e.g., message.reply)
X-Tuco-TimestampISO 8601 timestamp
Content-Typeapplication/json

Common Use Cases

  • SMS Fallback: Tuco sends P2P SMS from the line when it's on. If it's off, use message.fallback to route the text yourself
  • CRM Updates: On message.reply, update the contact record in HubSpot or Salesforce
  • Team Alerts: On message.reply, post to Slack or email the account owner
  • Marketing automation: Point the webhook at a webhook-triggered Customer.io journey and every reply becomes a tuco_message_reply event on the person, so other journeys can exit or branch on it
  • Analytics: Track delivery rates, reply rates, and fallback percentages

Webhooks are available on all Tuco plans. Set up your first webhook or book a demo.

About the author

Founder of Tuco AI and InboxPirates Consulting. Operates iMessage follow-up infrastructure on dedicated Apple hardware for B2B and B2C teams.

See Tuco in action

reply rates of 15-65% across customer accounts

Get Started