How to Set Up iMessage Webhooks with Blue Replies

What Are Webhooks?

Webhooks are HTTP callbacks that Blue Replies sends to your server when events happen — a message is delivered, read, or when you receive a reply. Instead of polling our API every few seconds to check for updates, webhooks push data to you in real time. This is more efficient, faster, and uses fewer API calls.

Step 1: Create a Webhook Endpoint

First, you need an HTTP endpoint that can receive POST requests. Here is a basic Express.js implementation:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

// Verify webhook signature to ensure requests come from Blue Replies
function verifySignature(req, secret) {
  const signature = req.headers['x-bluereplies-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

app.post('/webhooks/bluereplies', (req, res) => {
  // Always verify the signature first
  if (!verifySignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type);

  // Respond immediately with 200 to acknowledge receipt
  res.status(200).send('OK');

  // Process the event asynchronously
  handleEvent(event);
});

app.listen(3000, () => console.log('Webhook server running on :3000'));

Step 2: Handle Different Event Types

Blue Replies sends several event types. Here is how to handle each one:

async function handleEvent(event) {
  switch (event.type) {
    case 'message.sent':
      // Message accepted by Blue Replies and queued for delivery
      console.log('Message queued:', event.data.messageId);
      break;

    case 'message.delivered':
      // Message delivered to recipient's device
      console.log('Delivered:', event.data.messageId);
      await updateMessageStatus(event.data.messageId, 'delivered');
      break;

    case 'message.read':
      // Recipient opened the message
      console.log('Read at:', event.data.readAt);
      await updateMessageStatus(event.data.messageId, 'read');
      break;

    case 'message.failed':
      // Delivery failed — check error code
      console.error('Failed:', event.data.messageId, event.data.error);
      await handleFailedMessage(event.data);
      break;

    case 'message.received':
      // Incoming message from a customer
      console.log('From:', event.data.from, 'Body:', event.data.body);
      await handleIncomingMessage(event.data);
      break;

    default:
      console.log('Unknown event type:', event.type);
  }
}

Step 3: Register Your Webhook in the Dashboard

Navigate to Settings → Webhooks in your Blue Replies dashboard. Enter your endpoint URL and select which events you want to receive. We recommend starting with all events and filtering later based on your needs.

After saving, Blue Replies will send a verification ping to your endpoint. Your server must respond with a 200 status code within 5 seconds to confirm the webhook is active.

Step 4: Handle Retries and Failures

Blue Replies retries failed webhook deliveries with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: 30 seconds later
• Attempt 3: 2 minutes later
• Attempt 4: 10 minutes later
• Attempt 5: 1 hour later (final attempt)

If all 5 attempts fail, the event is moved to a dead-letter queue accessible through the dashboard. You can replay failed events manually once your endpoint is back online.

Best practices for reliability:

• Always respond with 200 immediately, then process asynchronously
• Use a message queue (like Redis or SQS) to handle spikes in webhook volume
• Implement idempotency — each event includes a unique eventId to prevent duplicate processing
• Log raw payloads for debugging

Step 5: Test with the Webhook Debugger

The Blue Replies dashboard includes a webhook debugger that shows every event sent to your endpoint, the response received, and any errors. Use this to verify your integration is working correctly before going to production.

You can also send test events from the debugger to simulate different scenarios — message delivered, message read, incoming message, delivery failure — without sending actual iMessages.

Common Patterns

Once your webhooks are set up, you can build powerful automations:

• Read receipt → CRM update: When a customer reads your message, update their record in your CRM
• Incoming message → Support ticket: Create a help desk ticket when a customer replies
• Delivery failure → Fallback SMS: If iMessage delivery fails, automatically send via SMS
• Message read but no reply → Follow-up: Trigger a follow-up message for customers who read but did not respond within 24 hours