Delivery Callbacks (Webhooks) & Signature Verification

The Rayo SMS Callback API (Webhooks) automatically notifies your server in near real-time whenever an outbound SMS message reaches a final delivery state (sent, delivered, not_delivered, unknown_delivery, or failure)—eliminating the need to poll GET /v1/check_status.

---

Configuring Your Callback Endpoint

You can configure and test your webhook listener in the Web Application under Advanced -> Settings -> Callbacks (/settings/callbacks).

1. Navigate to Advanced (top bar) -> Settings -> Callbacks (/settings/callbacks).
2. Set Enabled to Yes.
3. In the URL (Callback URL) field, enter the full HTTPS URL of your webhook endpoint.
4. Select your preferred HTTP Verb: get or post.
5. Click Test to send a live test webhook request from Rayo SMS to your server. Verify that your endpoint responds with HTTP 200 OK and that the banner displays:

   Callback API Properties seem to be Ok

6. Click Save to persist your configuration.

Disabling Callbacks

To stop receiving webhook notifications and clear your stored endpoint settings, click Delete and Disable Callback URL on the Callbacks settings page.

---

Verifying Webhook Signatures (Signing Secret)

Because your webhook URL is publicly reachable on the internet, your server should verify that every incoming callback genuinely originated from Rayo SMS and was not tampered with or spoofed by a third party.

• Signature Header: Every callback HTTP request sent by Rayo SMS includes a cryptographic signature in the Rayo-SMS-Signature HTTP header.
• Account Signing Secret: The signature is computed using your account’s unique Signing Secret (displayed next to Signing Secret: on the Advanced -> Settings -> Callbacks page).
• Implementation Details: See the API Reference Callback section (https://sms-api-docs.rayo.gr) for the exact HMAC signature verification algorithm, query/body payload parameters, and retry behavior.

---

Zero-Downtime Signing Secret Rotation (Expire Signing Secret)

If your security policy requires periodic key rotation—or if you suspect your current Signing Secret may have been exposed—you can schedule a controlled expiration in Advanced -> Settings -> Callbacks:

1. Open Advanced -> Settings -> Callbacks (/settings/callbacks).
2. Next to your Signing Secret, click Expire secret….
3. Select when the current secret should expire to give your engineering team time to prepare for the rotation.
4. If you need to abort a scheduled rotation before the timer elapses, click Do not expire secret… to cancel the pending expiration.
5. Once the scheduled expiration time is reached, the old secret is automatically retired and a new Signing Secret is generated immediately.