> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS Webhooks Introduction

> Receive SMS webhook events from Hypersender: message sent, delivered, failed, received, and scheduled events, plus phone heartbeats.

## Hypersender SMS Webhooks

The Hypersender SMS API offers a webhook-based integration that delivers real-time, event-driven notifications. This allows developers to monitor their connected phones (sms app) or respond to specific events.

* **Monitor Message Status**: Provides real-time updates on the status of sent messages, such as when the message is queued to be sent or has been successfully delivered.

* **Receive Incoming Messages**: Get notified when a new message is received on the connected phone.

* **Monitor Connected Phone**: Receive periodic heartbeats from your connected phone to ensure the connection is active and act when the phone is offline.

## Configure the webhook

**1. Open your instance settings**

Sign in to the [Hypersender dashboard](https://app.hypersender.com) and open the settings for the instance connected to your Android phone.

**2. Set the webhook URL**

Paste the public HTTPS endpoint that should receive the events. Hypersender POSTs a JSON payload to this URL for every event.

**3. Acknowledge quickly**

Reply with a 2xx status as soon as you receive the payload. If your handler needs more time, queue the payload and process it in the background.

> [!WARNING]
>
> The webhook URL must be publicly reachable over HTTPS. Requests to localhost or plain HTTP are not delivered.

## Events

| Event | Fires when |
| - | - |
| [`message-sent`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-sent) | The phone handed your message to the carrier |
| [`message-delivered`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-delivered) | The carrier confirmed delivery |
| [`message-failed`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-failed) | Sending the message failed |
| [`message-received`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-received) | Inbound SMS arrived on the connected phone |
| [`message-scheduled`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-scheduled) | A scheduled message was queued |
| [`message-expired`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-expired) | A queued message expired before it was sent |
| [`message-call-missed`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-call-missed) | A call was missed on the connected phone |
| [`heartbeat-online`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-online) | The phone reported that it is online |
| [`heartbeat-offline`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-offline) | The phone stopped reporting |
| [`heartbeat-missed`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-missed) | A scheduled heartbeat was not received |
| [`heartbeat-received`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-received) | A heartbeat arrived from the phone |
| [`heartbeat-disabled`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-disabled) | Heartbeat monitoring was turned off |

## Best practices

* Handle each event idempotently, keyed on the message or heartbeat identifier in the payload.
* Keep the handler fast: persist the payload first, then do the slow work asynchronously.
* Log every payload for at least a few days so you can replay events while integrating.
* Alert on `heartbeat-offline` and repeated `message-failed` events — both usually mean the phone needs attention.

## Next steps

> [card] [Receiving SMS Messages](https://docs.hypersender.com/v2/hypersender/overview/sms/receiving-sms-messages.md)
>
> End-to-end flow for handling inbound replies.

> [card] [Handle webhooks in Laravel](https://docs.hypersender.com/v2/packages-and-sdks/laravel/sms/sms-webhook-handling-and-events.md)
>
> Use the SDK's webhook controller and job instead of writing raw handlers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.