Create webhook

Creates a new webhook subscription for a line. The server generates an HMAC secret returned once on creation (also visible in the dashboard).

Delivery format

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: <hex hmac>
X-Webhook-Timestamp: <unix ms>
X-Webhook-Delivery-Id: dlv_<uuid>

{
  "event": "message.received",
  "data": { ... },
  "timestamp": <unix ms>,
  "delivery_id": "dlv_..."
}

Signature

X-Webhook-Signature is the lowercase hex HMAC-SHA256 of ${timestamp}.${rawBody} using the webhook secret. Verifiers should use the X-Webhook-Timestamp header (or the timestamp field in the body) to construct the signed payload, and reject deliveries whose timestamp is more than 5 minutes off (replay protection).

The @messages-dev/sdk package’s verifyWebhook() helper performs all of this for you, including timing-safe comparison.

POST /v1/webhooks

Create webhook

cURL

curl --request POST \
  --url https://api.messages.dev/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "[phone]",
  "url": "https://example.com/webhooks",
  "events": [
    "message.received",
    "message.sent"
  ]
}
'

201

{
  "id": "<string>",
  "line_ids": [
    "<string>"
  ],
  "url": "<string>",
  "events": [
    "<string>"
  ],
  "secret": "<string>",
  "is_active": true,
  "request_id": "<string>"
}

Authorizations

Authorization · string · header · required

Use an API key as a bearer token: Authorization: Bearer sk_live_...

Each key has a set of scopes that gate which endpoints it can call: messages:read, messages:write, chats:read, lines:read, reactions:read, reactions:write, typing:read, typing:write, receipts:read, receipts:write, webhooks:read, webhooks:write, outbox:read, files:read, files:write. Keys can also be restricted to a subset of lines.

Body

application/json

from · string · required

Line handle (phone number or Apple ID) to subscribe to

Example:

"[phone]"

url · string<uri> · required

HTTPS URL to receive webhook deliveries

Example:

"https://example.com/webhooks"

events · enum<string>[] · required

Events to subscribe to. See the schemas MessageReceivedEvent, MessageSentEvent, ReactionAddedEvent, ReactionRemovedEvent below for the data payload of each event.

Typing indicators (typing.started / typing.stopped) and inbound read receipts (receipt.read) are not delivered today; they will return when the underlying macOS-side detection layer surfaces them.

Available options: message.received, message.sent, reaction.added, reaction.removed

Example:

["message.received", "message.sent"]

Response

201

application/json

Webhook created

id · string

Webhook ID (e.g. wh_abc123)

line_ids · string[]

Line IDs this webhook is subscribed to (e.g. ["ln_abc123"])

url · string<uri>

events · string[]

secret · string

HMAC secret for verifying webhook signatures

is_active · boolean

request_id · string