Inbound SMS webhooks

Register a URL once and LumisReach POSTs an sms.received event to it every time someone texts one of your numbers, telling you who texted (their number and contact record), which of your numbers they texted, and what they said. Works for every number on your account, whichever carrier it runs on.

1. Register your endpoint

curl -X POST "https://api.lumisreach.com/api/v1/sms/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/lumisreach/sms", "phone_number_id": 12 }'

Leave out phone_number_id to hear about texts to all your numbers. The URL must be public HTTPS. The response includes a secret (whsec_…). It is shown only once: store it now, you need it to verify deliveries. Lost it? Delete the webhook and create a new one.

2. Receive `sms.received`

POST /lumisreach/sms HTTP/1.1
Content-Type: application/json
X-LumisReach-Event: sms.received
X-LumisReach-Event-Id: evt_6f1c…
X-LumisReach-Signature-256: 5d41402abc4b2a76b9719d911017c592…

{
  "id": "evt_6f1c2e4a-…",
  "type": "sms.received",
  "created_at": "2026-09-25T17:04:12.381Z",
  "test": false,
  "data": {
    "message_id": "6f1c2e4a-…",
    "from": "+14155550123",
    "to": "+14157279482",
    "phone_number_id": 12,
    "body": "Hey, is Thursday still good?",
    "received_at": "2026-09-25T17:04:12.102Z",
    "contact": {
      "id": "5f25da85-…",
      "name": "Jane Doe",
      "phone_number": "+14155550123",
      "email": "jane@example.com"
    }
  }
}

Field	Meaning
`data.from`	Who texted you.
`data.contact`	Their contact record. A first-time texter gets one automatically, named after their number.
`data.to`	Which of your numbers they texted.
`data.phone_number_id`	That number’s id, as in `GET /v1/phone-numbers`.
`data.body`	The message.
`id`	Unique per text. Use it to ignore a duplicate if a retry arrives after you already handled it.

Respond with any 2xx within 10 seconds. To see the full thread with this person, call GET /v1/history/texts?phone_number=<from>; for everything else you know about them, call GET /v1/contacts/<data.contact.id>.

3. Verify the signature

X-LumisReach-Signature-256 is the hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. It is the same scheme LumisReach call webhooks use.

import { createHmac, timingSafeEqual } from "crypto";

export function isFromLumisReach(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  );
}

Compute it over the body exactly as received, before any JSON parsing.

Retries

The first delivery is made right away. If your server errors, times out, or returns a non-2xx (redirects are not followed), it is retried 3 more times: after 1, 5 and 30 minutes. Every attempt is recorded in the webhook delivery log in your dashboard.

Test it

POST /v1/sms/webhooks/{id}/test sends a sample, correctly signed event with "test": true and tells you how your server responded.

Getting Started

Concepts

Quick Agent Actions

Conversation History

Phone Numbers

Caller IDs

Enterprise Registration

Enterprise Registration (Legacy)

Branded Calling

Calls