Forwarding received SMS

Every SMS your phones receive lands in Conversations. If another tool must react to it too, the gateway can tell that tool about each received SMS by calling its web address: a webhook listening to the message.received event.

Webhooks are managed on the Webhooks page, in the Automation section of the sidebar, right under Rules. This guide covers the most common case, forwarding received SMS. Everything else the page does (other events, every field, the delivery log and its filters) is described in Configure a webhook from the dashboard.

What forwarding is for

Creating a ticket in your helpdesk when a customer writes.
Starting an n8n or Make scenario on every incoming SMS: log it in a spreadsheet, alert a team channel, answer from an AI assistant.
Keeping your CRM's history of exchanges up to date.

For automatic replies inside the gateway itself, no external tool is needed: see Automation.

How it works

A phone receives an SMS and hands it to the gateway.
For each active webhook listening to message.received, the gateway queues a delivery and calls your address, usually within a few seconds.
Your tool answers with a 2xx status: the delivery is Delivered. Any other answer, no answer within 10 seconds, or a redirect counts as a failure, and the gateway tries again later (5 attempts over about 1 h 15 min).

What your address receives

The call carries the identifiers of the message, never its content:

{
  "event": "message.received",
  "at": "2026-09-21T08:14:03.512Z",
  "id": "0192f0c4-9d2a-7e11-b3c5-6a8f1e2d4c70",
  "conversationId": "0192f0a1-44be-7a02-8e19-3c7d5b9f0e21",
  "deviceId": "0192ef77-1c0d-7b3a-a5e4-9f2c8d1b6e03"
}

The text of the SMS and the full phone number never leave the gateway in this call. Your tool reads them through the API, with a key whose scope you choose: GET /api/v1/messages/{id} returns the message. This way, a leaked address reveals nothing, and you decide exactly which tool may read what. See Using the API and API keys.

Every call is signed: your tool checks the X-Signature header with the signing secret and refuses a call more than five minutes old. The Verify the signature panel of the Webhooks page sums up the checks, and Verify the signature has code examples.

Forward received SMS in four steps

Open Webhooks in the sidebar and click Forward received SMS. The form opens with the event message.received already ticked.
Fill in Name (for you) and URL (the address of your tool). Keep Method on POST unless your tool expects otherwise, and add a Custom header if your tool requires a token.
Leave Signing secret (optional) empty and click Create.
The Signing secret window shows the secret once, with a copy button. Paste it into your tool, then click I have copied the secret: it will never be displayed again.

Each field has a small "i" that explains it when you hover it. You can tick more events in the same form, for example message.failed to be told about failed sends too.

Follow what was sent

In the list, the State column says whether the webhook is Active, Paused (you turned it off) or Disabled after failures (the gateway turned it off after 100 deliveries given up in a row), and Failures in a row counts the deliveries given up since the last success.
The Delivery log tab lists every call with your tool's answer. Filter it on Event message.received, or use View deliveries in the menu of the webhook's row.
Replay the delivery sends a delivery again, freshly signed, typically after you fixed a bug in your tool and want to process the messages it missed.
Pause and Turn back on, in the menu of the row, stop and restart the forwarding. Received SMS that arrive during a pause are not sent later: read them through the API (GET /api/v1/messages?direction=in).

Who can do what

Role	Webhooks page
Read only	See the list and the delivery log
Operator, Superadmin	Create, edit, pause, turn back on, delete, replay

Troubleshooting

What you see	Why, and what to do
Failed with an error mentioning a blocked or loopback address	The URL points at `localhost` or the machine itself. Use its network address (for example `http://192.168.1.20:5678/...`)
Failed with HTTP code `301` or `302`	Redirects are not followed. Put the final address in URL (often `https://` instead of `http://`)
Failed with HTTP code `401` or `403`	Your tool expects a token: add it in Custom headers, or your tool rejects the signature
Your tool rejects the signature	Wrong secret, or the signature is computed on a re-serialised body. Sign the raw body exactly as received
Your tool refuses calls as too old	Its clock is off. Synchronise it (NTP): the tolerance is five minutes
Disabled after failures	Your tool failed 100 deliveries in a row. Fix it, then Turn back on, then replay what it missed
The payload has no text	Expected: read the message with `GET /api/v1/messages/{id}`

More causes, the retry table and the addresses the gateway refuses to call are in Webhooks.