Incoming SMS webhooks and security
Your provider sends incoming SMS to the Webhook URL generated by the connection in the SessionCloud portal. The portal stores the message and requests a notification through the app’s push server. The phone does not host an internet webhook listener.
Use HTTPS and copy the generated URL exactly. Do not replace it with a push-server hostname, phone address or generic example endpoint.
Provider reference
All incoming SMS callbacks use POST.
| Provider | Provider configuration | Authentication checked by SessionCloud | Payload |
|---|---|---|---|
| Telnyx | Messaging Profile Webhook URL; assign the number to that profile | Ed25519 signature using the saved public key, with a five-minute timestamp window | Telnyx JSON event |
| Twilio | Number’s A message comes in webhook, or its effective Messaging Service configuration | X-Twilio-Signature using the saved Auth Token and exact public URL; Account SID must match | Twilio URL-encoded form |
| A&A | Number’s SMS Inbound HTTPS target | Private credential in the generated URL | Form fields oa, da, ud, scts |
| Custom HTTPS | Provider’s incoming SMS callback | Private URL credential, or X-SessionTalk-Webhook-Token | Configured top-level JSON or form fields |
Generated paths have the form /api/v1/byo-messaging/webhooks/{provider}/{connection-id}. Provider values are telnyx, twilio, aa and custom. A&A and Custom URLs also contain their private token parameter. These path examples are not usable account configuration; copy your own URL from the portal.
Telnyx and Twilio delivery-status callbacks share their connection’s listener. The service supplies the outgoing message callback URL, including its correlation parameter, when it sends a message. Do not manually replace that parameter. A&A and Custom delivery-report callbacks are not implemented.
Keep the credentials separate
| Credential | Where it belongs |
|---|---|
| Provider API key, Auth Token or outgoing SMS password | The portal’s provider connection; local outbound app settings only when deliberately using that separate override |
| Telnyx public key | The portal’s Telnyx connection, for signature verification |
| A&A/Custom webhook credential | The provider’s callback URL or supported header |
| App setup code / mailbox token | The intended app account through private provisioning or App setup |
The private callback URL is a credential, even though it looks like a normal link. Do not publish it or include it in screenshots, browser analytics, monitoring exports or support logs. Remove query strings and authentication headers from diagnostics. Your provider may retain callback URLs in its own configuration or logs, so restrict access there too.
For A&A/Custom, Replace webhook credential invalidates the old callback credential immediately. Update the provider with the newly generated URL and test again. It does not change the outgoing SMS password or the app’s mailbox token. After changing Telnyx/Twilio credentials, update the portal connection to match; do not disable signature checking.
Acknowledgement and retries
Messages are stored before a successful response. Provider event/message IDs prevent duplicate delivery; A&A uses its sender, destination, timestamp and content because its callback has no separate message ID. Custom providers should send a stable unique ID and reuse it on retries.
| Response | Meaning / action |
|---|---|
200 | Accepted or already processed; this does not confirm that a phone displayed a notification. An unassigned number can also be acknowledged without delivery to an inbox. |
400 | Invalid payload, fields or identifiers; check mappings and the provider format. |
403 | Invalid/missing callback credential or signature; correct the configuration. |
404 | Connection missing, disabled or using the wrong provider/path. |
413 | Payload too large; the incoming listener accepts at most 256 KiB. |
429 | A&A/Custom callback rate limit; retry later using the same ID/timestamp. |
5xx | Processing was unavailable; follow the provider’s retry policy. |
Twilio receives an empty TwiML response on success; the other adapters receive JSON acknowledgement. A&A/Custom currently allow 300 callbacks per minute per source IP across those adapters. Do not retry a rejected request with a new message ID to bypass deduplication.
Acceptance test
Confirm the assigned number and SIP identity, then test foreground receipt, locked-phone notification, notification tap, offline catch-up, duplicate callbacks and an outgoing reply. Also confirm that an invalid credential/signature is rejected. Test only numbers and devices you are authorized to use.
The provider’s delivery log, portal Last received SMS, portal registered-device count and the phone’s displayed message each prove different stages. Record the time and message ID when requesting help, and redact credentials. See Troubleshooting SMS.