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

# Webhooks

> Get real-time notifications when SMS arrives or order status changes.

<Note>
  Webhooks are available on request. Contact support to enable for your account.
</Note>

VirtualSMS can send HTTP POST requests to your endpoint when:

* An SMS arrives on your number
* An order expires
* A deposit is confirmed

## Payload format

```json theme={null}
{
  "event": "sms_received",
  "order_id": "abc123",
  "phone_number": "+447911123456",
  "service": "telegram",
  "sms_code": "12345",
  "full_text": "Telegram code: 12345",
  "received_at": "2026-03-15T12:00:00Z"
}
```

## Events

| Event               | Description                        |
| ------------------- | ---------------------------------- |
| `sms_received`      | SMS arrived on your number         |
| `order_expired`     | Order expired with no SMS          |
| `deposit_confirmed` | Crypto deposit credited to balance |

## Security

Requests include an `X-Signature` header: HMAC-SHA256 of the raw body using your webhook secret.

```python theme={null}
import hmac, hashlib

def verify(secret, body, signature):
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```