Webhook events

The event types Hellio delivers to your webhook endpoints. Subscribe to specific events, or * for all.

Message events

Fired when a message reaches a final delivery state.

Event	When it fires
`message.delivered`	The carrier confirmed delivery to the handset.
`message.undelivered`	The carrier could not deliver (e.g. phone off, out of coverage).
`message.failed`	The send failed before or during submission.
`message.rejected`	The carrier or sender rules rejected the message.
`message.expired`	The message validity period elapsed before delivery.

Payload

Each delivery is a JSON POST to your endpoint.

{
  "event": "message.delivered",
  "mobile_number": "+233241234567",
  "provider_message_id": "abc123",
  "status": "delivered",
  "timestamp": "2026-06-30T10:24:01+00:00"
}

The status mirrors the event (delivered, undelivered, failed, rejected, expired). Match deliveries to your sends with provider_message_id.

Every delivery is signed. Always verify the signature before trusting a payload, see Webhooks.

Subscribing

Pick events when you register an endpoint.

Pass an events array (or omit for all) when creating an endpoint via the dashboard or the API:

{
  "url": "https://example.com/hooks/hellio",
  "events": ["message.delivered", "message.failed"]
}

See POST /v1/webhooks in the API reference.