Receive inbound SMS with an HTTPS endpoint

Receive inbound SMS as JSON POST requests to your HTTPS webhook.

Before you start

Your webhook must be publicly reachable over HTTPS with a valid certificate.

Configure cloudnumbering

Create an SMS endpoint whose URI is your webhook URL, then assign it to the number that will receive messages. Configure the endpoint in the cloudnumbering portal, or use the API endpoint and number-routing operations.

Your handler must accept JSON POST requests and return a 2xx response after it accepts a message.

Request body

cloudnumbering sends this JSON shape:

{
  "to": "+447700900000",
  "from": "+447700900001",
  "content": "Example message",
  "country": "GB",
  "country_name": "United Kingdom",
  "parts": 1
}

Field	Type	Meaning
`to`	string	Your cloudnumbering number in E.164 format.
`from`	string	The sending number or alphanumeric sender ID.
`content`	string	Message text.
`country`	string	Two-letter country code of the cloudnumbering number that received the message.
`country_name`	string	Country name of the cloudnumbering number that received the message.
`parts`	integer	Number of SMS parts used by the message.

Handle requests safely

The request does not include a cloudnumbering signature or message identifier. Treat every field as untrusted input.
Do not assume that from is a phone number. It can contain an alphanumeric sender ID.

Treat all fields as optional. A field is omitted from the JSON when it has no value, so country and country_name are absent for messages from shortcodes and alphanumeric senders, and content is absent for an empty message. A handler that requires every field will reject valid traffic.

Handle retries and missed messages

Build the handler to this contract rather than to an observed retry pattern:

Transport failures can be retried, so the same message can arrive more than once. Make processing idempotent.
A non-2xx response does not trigger another attempt. Return 2xx as soon as you have stored the message, then process it asynchronously.
There is no facility to replay missed messages, so a message your handler rejects can be lost.

Warning: Because a non-2xx response does not trigger another attempt, a handler that validates strictly and rejects unexpected input can silently lose inbound messages. Accept first, validate after.

Troubleshooting

My webhook receives no requests

Confirm that the endpoint is assigned to the intended number, its URI starts with https://, and the hostname resolves publicly.

Delivery stopped after working previously

Check the certificate expiry and chain, then review your server logs for connection failures and non-2xx responses.

My handler rejects `from`

Accept either an E.164 number or an alphanumeric sender ID, and treat the value as untrusted text.