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

# Webhook Events

> Get notified on your server when SMS is sent, delivered, fails, or when someone replies.

<Tip>
  With the API you **ask**; with webhooks Notifique **notifies**. Ideal to mark an order delivered or process a customer reply without polling.
</Tip>

## In brief

* Every delivery is a **POST** `application/json` to your registered URL.
* `sms.*` events are **SMS only**, WhatsApp uses `message.*`.
* `instanceId` is always **empty** (SMS does not use instances).
* Enable **only** the events your integration needs.
* Reply **2xx quickly**; heavy work goes to a queue on your side.

General setup: [Webhooks](/en/guides/webhooks/index). Security (HMAC signature): [Webhook security](/en/guides/webhooks/seguranca).

***

## How the POST looks

```json theme={null}
{
  "event": "sms.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}
```

| Field         | Description                                       |
| ------------- | ------------------------------------------------- |
| `event`       | Event name (e.g. `sms.delivered`)                 |
| `workspaceId` | Workspace ID                                      |
| `instanceId`  | Always empty for SMS                              |
| `timestamp`   | ISO 8601, use for anti-replay                     |
| `data`        | Send or MO fields (`smsId`, `to`, `status`, etc.) |

Headers: `X-Notifique-Signature`, `X-Notifique-Timestamp`, `X-Workspace-Id`, `X-Webhook-Event`.

***

## What your server should return

| Response                | Effect                               |
| ----------------------- | ------------------------------------ |
| **2xx** within \~10s    | Event delivered; removed from queue  |
| **4xx / 5xx / timeout** | Automatic retry (5 min, 30 min, 2 h) |

<Note>
  Slow processing? Reply **200** immediately and process in the background. Over \~10 s counts as timeout and the event may be redelivered.
</Note>

Validate `X-Notifique-Signature` and a recent timestamp. Details: [Webhook security](/en/guides/webhooks/seguranca).

***

## Event reference

Use these events when integrating **ERP, e-commerce, or automation** with SMS.

### Send and status

| Event           | When it fires               | What to do with it        |
| --------------- | --------------------------- | ------------------------- |
| `sms.sent`      | Carrier accepted the SMS    | Mark as sent              |
| `sms.delivered` | Confirmed delivered (DLR)   | Confirm delivery, billing |
| `sms.clicked`   | Short link click in the SMS | Campaign / conversion     |
| `sms.failed`    | Send failure or error DLR   | Retry or alert            |
| `sms.cancelled` | Scheduled send cancelled    | Update order              |

### Inbound messages (MO)

| Event          | When it fires                           | What to do with it          |
| -------------- | --------------------------------------- | --------------------------- |
| `sms.received` | Customer **sent an SMS** to your number | Keyword, opt-in, support    |
| `sms.replied`  | Reply **linked to your outbound send**  | “YES/NO” confirmation, poll |

<Info>
  MO follows inbound rules in **Settings → Received messages**, like other channels. Guide: [Inbound messages](/en/guides/webhooks/mensagens-recebidas-e-respostas).
</Info>

***

## Payload per event

Full POST body. The envelope (`event`, ids, `timestamp`) matches the example above; below is what changes in `data`.

<AccordionGroup>
  <Accordion title="sms.sent">
    ```json theme={null}
    {
      "event": "sms.sent",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:29:00.000Z",
      "data": {
        "smsId": "clxx456...",
        "to": "5511999999999",
        "status": "SENT",
        "sentAt": "2025-02-10T14:29:00.000Z",
        "externalId": "ext-abc123",
        "provider": "zenvia"
      }
    }
    ```
  </Accordion>

  <Accordion title="sms.delivered">
    ```json theme={null}
    {
      "event": "sms.delivered",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:30:00.000Z",
      "data": {
        "smsId": "clxx456...",
        "to": "5511999999999",
        "status": "DELIVERED",
        "deliveredAt": "2025-02-10T14:30:05.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="sms.failed">
    ```json theme={null}
    {
      "event": "sms.failed",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:29:30.000Z",
      "data": {
        "smsId": "clxx456...",
        "to": "5511999999999",
        "status": "FAILED",
        "failedAt": "2025-02-10T14:29:30.000Z",
        "errorMessage": "invalid_number"
      }
    }
    ```
  </Accordion>

  <Accordion title="sms.cancelled">
    ```json theme={null}
    {
      "event": "sms.cancelled",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T12:00:00.000Z",
      "data": {
        "smsId": "clxx456...",
        "to": "5511999999999",
        "status": "CANCELLED"
      }
    }
    ```
  </Accordion>

  <Accordion title="sms.clicked">
    Fires on the **first** click on a tracked short link from this SMS.

    ```json theme={null}
    {
      "event": "sms.clicked",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:35:00.000Z",
      "data": {
        "smsId": "clxx456...",
        "to": "5511999999999",
        "status": "CLICKED",
        "clickedAt": "2025-02-10T14:35:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="sms.received">
    ```json theme={null}
    {
      "event": "sms.received",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T15:00:00.000Z",
      "data": {
        "inboundId": "clxxinbound001",
        "from": "5511999999999",
        "bodyPreview": "YES",
        "receivedAt": "2025-02-10T15:00:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="sms.replied">
    When the MO is **linked** to your outbound send (e.g. poll reply).

    ```json theme={null}
    {
      "event": "sms.replied",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T15:00:00.000Z",
      "data": {
        "smsId": "clxx456...",
        "inboundId": "clxxinbound001",
        "from": "5511999999999",
        "replyText": "YES",
        "status": "REPLIED"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

* [Quick Start](/en/sms-api/como-funciona/quick-start): first send
* [Introduction](/en/sms-api/como-funciona/introducao): status lifecycle
* [Scopes](/en/sms-api/como-funciona/escopos-da-api-key): key permissions
* [Webhooks (general guide)](/en/guides/webhooks/index)