Skip to main content
Webhooks let you receive instant, server-to-server notifications when events occur in Hany — no polling required. Instead of repeatedly querying the API to check whether an SMS was delivered, Hany sends an HTTP POST request directly to a URL you specify the moment the event happens.

​
How Webhooks Work

1

Provide a callback URL

Include a callback_url in your send request. This is the HTTPS endpoint on your server that Hany will call when an event fires.
2

Hany sends an HTTP POST

When the event occurs (for example, a delivery confirmation arrives from the carrier), Hany sends an HTTP POST request to your callback_url with a JSON payload describing the event.
3

Acknowledge with HTTP 200

Your server must respond with an HTTP 200 OK status code to confirm receipt. Any response body is ignored — only the status code matters.
4

Automatic retries on failure

If your server does not respond with 200, Hany retries the delivery on a fixed schedule — up to 3 total attempts — before marking the event as undelivered. See the Retry Policy section for the exact schedule.

​
Registering a Webhook URL

Webhook URLs are configured per-request using the callback_url parameter on any send endpoint. There is no separate webhook registration step — simply include your endpoint URL when you send a message. 
curl -X POST https://api.hany.tools/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15550001234",
    "from": "YourBrand",
    "message": "Your order has shipped!",
    "callback_url": "https://yourapp.com/webhooks/hany"
  }'
When Hany receives a delivery status update for this message, it will POST the event payload to https://yourapp.com/webhooks/hany.

​
Webhook Security

Keep your webhook endpoint secure and resilient by following these best practices:
  • Use HTTPS only. Hany will not deliver webhooks to plain HTTP endpoints. Always use a valid TLS certificate.
  • Validate the payload structure. Check that the incoming payload contains the fields you expect before processing it. Reject malformed requests with a 400 status.
  • Respond within 5 seconds. Hany waits up to 5 seconds for a response. If your handler takes longer, move heavy processing to a background job and return 200 immediately.
  • Return HTTP 200 to acknowledge. Any status code other than 200 is treated as a failure and triggers a retry. This includes 2xx codes such as 201 or 204.
Do not perform database writes, API calls, or other slow operations synchronously inside your webhook handler. Respond with 200 first, then process the event asynchronously to prevent timeouts and duplicate deliveries.

​
Retry Policy

When your endpoint fails to return HTTP 200, Hany automatically retries the delivery on the following schedule:
AttemptTiming
Attempt 1Immediately
Attempt 230 seconds after Attempt 1
Attempt 35 minutes after Attempt 2
After 3 consecutive failures, Hany marks the webhook event as undelivered and stops retrying. Make sure your endpoint is reachable and returns 200 reliably to avoid missed events.
Each retry sends the same payload as the original request. Design your handler to be idempotent — processing the same event more than once should not cause unintended side effects.

​
Supported Events

The following webhook event types are currently available:
EventDescription
sms.deliveredSMS successfully delivered to the recipient
sms.failedSMS delivery failed after all carrier retries
sms.sentSMS dispatched from Hany’s gateway to the carrier network

Delivery Status Webhook

Full payload reference for sms.delivered, sms.failed, and sms.sent events, plus a server-side handling example.