Webhooks

Overview

Webhooks push events to your server as they happen, no polling required. Register a URL, choose which events you care about, and Messages.dev will POST to it in real time.

Events

Event	Description
`message.received`	A new incoming message on the line.
`message.sent`	An outgoing message was delivered.
`reaction.added`	Someone reacted to a message.
`reaction.removed`	Someone removed their reaction.

Inbound typing.started / typing.stopped and receipt.read are not delivered today — Apple’s underlying APIs surface those events on the macOS side but our daemon doesn’t expose them yet. Subscribing to them is currently rejected. They will return when the underlying detection layer ships.

Every event delivers a JSON body with the same envelope (event, data, timestamp, delivery_id) and the same set of headers (see Payload format). The shape of data depends on the event:

`message.received` and `message.sent`

data matches the Message resource and adds line_handle (your line’s phone number / Apple ID, included so you can route inbound events without a side lookup).

Field	Type	Notes
`id`	`string`	`msg_…`
`line_id`	`string`	`ln_…`
`line_handle`	`string`	The line’s phone number or Apple ID.
`chat_id`	`string`	`cht_…` — the conversation.
`guid`	`string`	iMessage GUID. Use as `reply_to` or to react.
`sender`	`string`	Phone number / Apple ID of who sent it.
`text`	`string \| null`	`null` when the message is attachment-only.
`attachments`	`Attachment[]`	Files attached to the message. Voice memos include `transcription`.
`is_from_me`	`boolean`	`true` for `message.sent`, `false` for `message.received`.
`is_audio_message`	`boolean \| null`	`true` for native voice memos.
`sent_at`	`number`	Unix ms.
`synced_at`	`number`	Unix ms when synced to messages.dev.
`reply_to_guid`	`string \| null`	iMessage GUID of the parent if this is a reply.

`reaction.added` and `reaction.removed`

data matches the Reaction resource and adds chat_id (so you can route the event to a thread without an extra getMessage call) and line_handle.

Field	Type	Notes
`id`	`string`	`rxn_…`
`message_id`	`string`	`msg_…` — the message being reacted to.
`chat_id`	`string`	`cht_…` — the conversation the message lives in.
`line_handle`	`string`	The line that received (or sent) the reaction.
`type`	`string`	`love` / `like` / `dislike` / `laugh` / `emphasize` / `question`.
`sender`	`string`	Phone number / Apple ID of who reacted.
`is_from_me`	`boolean`	True if your line was the reactor.
`added`	`boolean`	`true` for `reaction.added`, `false` for `reaction.removed`.
`sent_at`	`number`	Unix ms.
`synced_at`	`number`	Unix ms.

Creating a webhook

The easiest way to create a webhook is from the Webhooks page in your dashboard. Click Add Webhook, enter your URL, select the events you care about, and copy the signing secret.

The dashboard is the recommended way to manage webhooks. It shows the signing secret once on creation and makes it easy to enable, disable, or delete webhooks without writing code.

You can also create webhooks via the API:

import { createClient } from "@messages-dev/sdk";

const client = createClient();

const webhook = await client.createWebhook({
  from: "+15551234567",
  url: "https://your-server.com/webhooks",
  events: ["message.received", "message.sent"],
});

curl -X POST "https://api.messages.dev/v1/webhooks" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "url": "https://your-server.com/webhooks",
    "events": ["message.received", "message.sent"]
  }'

Each webhook is scoped to a single line. Create one per line if you have multiple lines.

Payload format

POST /webhooks HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: a1b2c3d4e5f6...
X-Webhook-Timestamp: 1710000000123
X-Webhook-Delivery-Id: dlv_abc...

{
  "event": "message.received",
  "data": {
    "id": "msg_abc123",
    "line_id": "ln_xyz",
    "line_handle": "+15551234567",
    "chat_id": "cht_def456",
    "sender": "+15559876543",
    "text": "Hey there!",
    "is_from_me": false,
    "is_audio_message": false,
    "attachments": [],
    "sent_at": 1710000000000
  },
  "timestamp": 1710000000123,
  "delivery_id": "dlv_abc..."
}

Each delivery includes three headers in addition to Content-Type:

Header	Description
`X-Webhook-Signature`	Hex HMAC-SHA256 over `${timestamp}.${rawBody}`
`X-Webhook-Timestamp`	Unix ms at delivery time. Reject if more than 5 minutes off (replay protection).
`X-Webhook-Delivery-Id`	Unique `dlv_...` ID for the delivery. Useful for idempotency on your side.

Voice memos

Inbound tap-to-record voice memos arrive on the same message.received event. The message has is_audio_message: true and the audio attachment carries the auto-generated transcription text from iMessage:

{
  "event": "message.received",
  "data": {
    "id": "msg_abc123",
    "line_id": "ln_xyz",
    "line_handle": "+15551234567",
    "chat_id": "cht_def456",
    "sender": "+15559876543",
    "text": null,
    "is_from_me": false,
    "is_audio_message": true,
    "attachments": [
      {
        "filename": "Audio Message.caf",
        "mime_type": "audio/x-caf",
        "size": 24576,
        "url": "https://files.messages.dev/...",
        "transcription": "Hey, can you grab milk on the way home?"
      }
    ],
    "sent_at": 1710000000000
  },
  "timestamp": 1710000000123
}

transcription may be null on the first delivery if Apple hasn’t finished on-device transcription yet (typically <2s after receipt). It is also null for non-voice-memo audio attachments (e.g. a drag-and-dropped MP3), which arrive with is_audio_message: false.

Verifying signatures

Every webhook delivery is signed with HMAC-SHA256 over the string ${timestamp}.${rawBody} using your webhook secret. The SDK handles signature verification, timing-safe comparison, and replay protection automatically:

import { verifyWebhook } from "@messages-dev/sdk";

app.post("/webhooks", async (req, res) => {
  const event = await verifyWebhook(
    req.body,
    req.headers["x-webhook-signature"],
    "your_webhook_secret",
  );

  console.log(event.event, event.data);
  res.sendStatus(200);
});

If the signature is invalid (or the timestamp is more than 5 minutes off), verifyWebhook throws a SignatureVerificationError. The default tolerance window can be overridden via the tolerance option (in milliseconds). If you’re not using the SDK, verify manually. Build the signed payload as ${timestamp}.${rawBody} — using ${rawBody} alone will always fail. The timestamp is available both as the X-Webhook-Timestamp header and as the timestamp field inside the parsed body:

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(rawBody, headers, secret, toleranceMs = 5 * 60_000) {
  const signature = headers["x-webhook-signature"];
  const timestamp = Number(headers["x-webhook-timestamp"]);
  if (!signature || !timestamp) return false;
  if (Math.abs(Date.now() - timestamp) > toleranceMs) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac
import hashlib
import time

def verify_webhook(raw_body: bytes, headers, secret: str, tolerance_ms: int = 5 * 60_000) -> bool:
    signature = headers.get("x-webhook-signature")
    timestamp = int(headers.get("x-webhook-timestamp", "0"))
    if not signature or not timestamp:
        return False
    if abs(int(time.time() * 1000) - timestamp) > tolerance_ms:
        return False

    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Always verify the signature before processing a webhook payload. This prevents attackers from sending forged events to your endpoint.

Testing webhooks locally

Use the CLI for live local development

The fastest way to iterate on a webhook handler locally is the messages-dev CLI. listen --forward-to subscribes to your account’s event stream and POSTs each real event to a local URL with the same HMAC headers production deliveries use, so you don’t need to register a webhook, run ngrok, or expose a public URL while you build:

messages-dev listen --forward-to http://localhost:3000/webhooks

The CLI prints a per-session HMAC secret on first run. Use it as the secret in your verifyWebhook() call, or pin one with MESSAGES_LISTEN_SECRET=…. Because the deliveries are genuinely signed, your verification code runs unchanged. If you’d rather exercise the production delivery path end-to-end, expose your local server with ngrok, Cloudflare Tunnel, or any other tunnel and register a real webhook pointing at the public URL. Same payload, same headers — only the source of the deliveries changes.

Synthesize signed deliveries in tests

For unit tests, where you want to drive the handler without a network round trip, the SDK exports two helpers that build real signed deliveries you can POST at your handler — no test-mode bypass needed. Your verifyWebhook() code path runs unchanged because the signature is genuine. buildWebhookDelivery(event, data, secret) is the high-level helper:

import { buildWebhookDelivery } from "@messages-dev/sdk";

const { body, headers } = await buildWebhookDelivery(
  "message.received",
  {
    id: "msg_test",
    lineId: "ln_test",
    lineHandle: "+15551234567",
    chatId: "cht_test",
    guid: "guid-test",
    sender: "+15559876543",
    text: "hello from a test",
    attachments: [],
    isFromMe: false,
    sentAt: Date.now(),
    syncedAt: Date.now(),
  },
  process.env.WEBHOOK_SECRET!,
);

await fetch("http://localhost:3000/webhooks", {
  method: "POST",
  body,
  headers,
});

For more control — building a full body yourself, signing on a different language, etc. — use the lower-level signWebhook(secret, timestamp, rawBody) helper which returns the lowercase hex HMAC-SHA256 of ${timestamp}.${rawBody}. This covers the unit-test inner loop: no isEmulator flag, no skipping signature verification, just real signed deliveries on demand. For end-to-end local dev with live events from your account, prefer messages-dev listen --forward-to above.

Deleting a webhook

You can delete webhooks from the Webhooks page in your dashboard, or in code:

await client.deleteWebhook({ id: "wh_abc123" });

curl -X DELETE https://api.messages.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"id": "wh_abc123"}'

When using the REST API directly, the webhook ID is passed in the request body, not in the URL path.

Getting Started

Guides

Concepts

Scaling

Overview

Events

`message.received` and `message.sent`

`reaction.added` and `reaction.removed`

Creating a webhook

Payload format

Voice memos

Verifying signatures

Testing webhooks locally

Use the CLI for live local development

Synthesize signed deliveries in tests

Deleting a webhook

​Overview

​Events

​message.received and message.sent

​reaction.added and reaction.removed

​Creating a webhook

​Payload format

​Voice memos

​Verifying signatures

​Testing webhooks locally

​Use the CLI for live local development

​Synthesize signed deliveries in tests

​Deleting a webhook

Overview

Events

`message.received` and `message.sent`

`reaction.added` and `reaction.removed`

Creating a webhook

Payload format

Voice memos

Verifying signatures

Testing webhooks locally

Use the CLI for live local development

Synthesize signed deliveries in tests

Deleting a webhook