Developer Documentation

Receive Delivery Events with Signed Webhooks

Webhooks let Alert21 notify your server when a message changes state so you do not need to continuously poll the API.

{
  "event": "sms.delivered",
  "message_id": "AL21SMS260824001234",
  "to": "919876543210",
  "status": "delivered",
  "delivered_at": "2026-08-24T14:00:05+05:30"
}

Example Delivery Event

{
  "event": "sms.delivered",
  "message_id": "AL21SMS260824001234",
  "to": "919876543210",
  "status": "delivered",
  "delivered_at": "2026-08-24T14:00:05+05:30"
}

Example signature header:

X-Alert21-Signature: <signature>

Webhook Handler Rules

Use HTTPS.
Verify the signature before trusting the payload.
Return a 2xx response quickly after durable acceptance.
Process heavy work asynchronously.
Make handlers idempotent because an event can be retried.
Do not rely on arrival order; use event/message timestamps and state logic.
Log the Alert21 event ID/message ID, not secrets.

Retry Policy

Webhook retry timing and availability depend on the active product configuration. Confirm the current retry schedule before relying on it, and keep your handler idempotent so repeated or out-of-order events remain safe.

Direct Answers

Frequently Asked Questions

Quick answers to common questions about Alert21 SMS API, telecom compliance, and developer integration.

What is an Alert21 delivery webhook?

A delivery webhook is an HTTPS callback that informs your server when a message status changes. It lets your application process delivery updates without continuously polling the API and associate each event with the Alert21 message ID stored during submission.

How should I secure an Alert21 webhook endpoint?

Use HTTPS, verify the Alert21 signature before trusting the payload, reject invalid signatures and avoid logging credentials or full sensitive message content. Keep verification secrets on the server and follow the current webhook documentation for the exact signing procedure.

Why must a webhook handler be idempotent?

A delivery event can be retried when your endpoint times out or does not acknowledge it successfully. Idempotent processing prevents the same event from triggering duplicate actions, while durable storage and state-transition rules protect against events arriving more than once or out of order.

EVERY ALERT. ONE API.

Turn your next business event into a traceable alert.

Start with DLT-ready SMS today on Alert21’s developer-first communication platform.

Start Free View API Docs