# Receive SMS events with webhooks

Create a public HTTPS endpoint, save its secret and verify signed events with duplicate-safe processing.

2026-10-07 · SMS.Red

## 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.