On this page
See how it works
Illustrated walkthrough · fictional sample data
Create a public HTTPS endpoint
Add a webhook with a public HTTPS URL. Localhost, private addresses, URL credentials, fragments and redirect destinations are not accepted.
This demonstration does not change your account.
Read all steps
- Create a public HTTPS endpoint
Add a webhook with a public HTTPS URL. Localhost, private addresses, URL credentials, fragments and redirect destinations are not accepted.
- Label
- Demo SMS receiver
- Endpoint
- https://example.com/sms-webhook
- Save the one-time secret
Copy the secret into your server’s protected configuration when shown. It is not available for later display; do not put it in tickets or public code.
- Signing secret
- ••••••••
- Verify the raw-body signature
Verify HMAC-SHA256 over the raw request body with the signing secret and compare the x-smsred-signature value. Use the stable x-smsred-event-id to deduplicate.
- Signature header
- x-smsred-signature: sha256=<hex>
- Event identity
- x-smsred-event-id: DEMO-EVENT-42
- Verify
- HMAC-SHA256(secret, rawBody)
- Acknowledge and handle retries
Return 2xx promptly after accepting the event safely. Failed delivery can retry up to 8 times with the same event identity; process one event once. Ownership is checked again before delivery.
- First delivery
- DEMO-EVENT-42 → 2xx
- Repeated delivery
- Same event ID → no duplicate action
- Manage the webhook
Edit its label or description, disable delivery temporarily, or delete it when no longer needed. Keep your receiver’s deduplication and secret handling consistent during changes.
- Webhook
- Demo SMS receiver
- Status
- Disabled
Add a public endpoint
In Developers, open Webhooks and Add endpoint. Enter a label, public HTTPS URL and optional description. Localhost, private-network addresses, credentials in the URL and redirects are unsuitable. Make the final destination directly reachable.
After creation, copy and securely save the secret shown by the modal. Copying clears this display; do not rely on being able to read it later. Keep it separate from API keys and out of public code.
Verify the original request body
Events arrive as JSON POST requests. Calculate HMAC-SHA256 with the webhook secret over the exact raw request body, then compare with x-smsred-signature, formatted sha256=HEX_DIGEST. Do not parse and reserialize JSON before verifying; whitespace can change the signature. Use a constant-time comparison in your implementation.
Use x-smsred-event-id as the stable event identifier. Verify authenticity, deduplicate that identifier, safely record/queue the work and return a 2xx response promptly. Follow the current event contract for body fields.
Expect retries and manage the endpoint
Delivery can retry non-2xx responses or timeouts up to eight attempts with backoff, so the same event can arrive more than once. Your handler must tolerate duplicates. A redirect does not count as a successful 2xx destination response.
The table supports editing label/description, disabling and removal. Disable pauses delivery; removal deletes the endpoint. Current ownership governs messages, including after transfers. For failures, check your HTTPS endpoint, signature handling and server logs; do not assume the dashboard has a full delivery-log viewer.
Need help with your account?
Open Support