iMessage Webhook Integration: Receive Messages in Real-Time

Webhooks are how your application receives iMessages in real-time. When someone texts your Sendblue number, a webhook delivers the message to your server within seconds. This guide covers everything: setup, payload structure, security, media handling, and best practices.

What Are Webhooks?

A webhook is an HTTP POST request that Sendblue sends to your server whenever an event occurs — like receiving a new message, a delivery confirmation, or a typing indicator. Instead of polling the API for new messages, webhooks push data to you in real-time.

Sendblue supports 7 webhook types: receive (incoming messages), outbound (delivery status updates), typing_indicator, call_log, line_blocked, line_assigned, and contact_created.

Setting Up Your Webhook Endpoint

import express from 'express';
const app = express();
app.use(express.json());

// Receive incoming iMessages
app.post('/webhooks/receive', (req, res) => {
  const {
    from_number,   // sender's phone number
    to_number,     // your Sendblue number
    content,       // message text
    media_url,     // URL of attached media (if any)
    service,       // "iMessage", "SMS", or "RCS"
    group_id,      // group conversation ID (if group)
    date_sent,     // ISO timestamp
  } = req.body;

  console.log(`[${service}] ${from_number}: ${content}`);

  if (media_url) {
    console.log(`  Media: ${media_url}`);
  }

  // Always respond with 2xx to acknowledge
  res.status(200).json({ received: true });
});

// Delivery status updates
app.post('/webhooks/status', (req, res) => {
  const { number, status, error_message } = req.body;
  console.log(`Delivery to ${number}: ${status}`);
  res.status(200).json({ received: true });
});

app.listen(3000);

Configure in Sendblue Dashboard

Go to your Sendblue dashboard → Settings → Webhooks. Set your webhook URLs:

Receive webhook: https://your-server.com/webhooks/receive
Status callback: https://your-server.com/webhooks/status

Local development: Use ngrok to expose your local server:

ngrok http 3000
# Copy the https URL and set it as your webhook

Handling Media Attachments

When a user sends an image, video, or file, the media_url field contains a URL to the file hosted on Sendblue's storage. Key details:

Media URLs are temporary — they expire after 30 days
Download and store media in your own storage if you need it long-term
All file types are supported: images, videos, audio, PDFs, contact cards
.caf files are voice notes; .vcf files are contact cards

Best Practices

Always return 2xx: If your endpoint doesn't respond with a 2xx status, Sendblue will retry the webhook. Return 200 immediately, then process asynchronously.
Idempotency: Webhooks may be delivered more than once. Use the message ID to deduplicate.
Queue processing: For high volume, acknowledge the webhook immediately and push processing to a background queue (Redis, SQS, etc.).
Error handling: Log all webhook payloads for debugging. If processing fails, you still have the raw data.

For the full webhook reference including all 7 webhook types, see the API documentation.

Webhooks

iMessage API

Tutorial

Node.js

Ready to send your first iMessage?

Get API access in minutes. Free sandbox, no credit card required.

Get API Access