> ## 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 message status changes, someone replies, or the instance connects.

<Tip>
  With the API you **ask**; with webhooks Notifique **tells you**. Like a banking app push when a transfer lands, your backend does not need to poll every second.
</Tip>

## In brief

* Every delivery is a **POST** `application/json` to the URL you registered.
* `message.*` and `instance.*` events are **WhatsApp only** (Telegram uses `telegram.*`).
* 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).

***

## What the POST looks like

Standard envelope for every event:

```json theme={null}
{
  "event": "message.read",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:00.000Z",
  "data": {
    "to": "5511999999999",
    "status": "READ"
  }
}
```

| Field         | Description                           |
| ------------- | ------------------------------------- |
| `event`       | Event name (e.g. `message.sent`)      |
| `workspaceId` | Workspace ID                          |
| `instanceId`  | WhatsApp instance ID                  |
| `messageId`   | Outbound message ID (when applicable) |
| `timestamp`   | ISO 8601, use for anti-replay         |
| `data`        | Event-specific fields (camelCase)     |

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

***

## What your server should return

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

<Note>
  Slow processing? Return **200** immediately and process in the background. Taking more than 10 seconds counts as a timeout and the event may be sent again.
</Note>

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

***

## Event reference

Use these events when integrating **bots, support, ERP, or automation** on WhatsApp.

<Note>
  The `message.*` names are **WhatsApp only**. Telegram uses `telegram.*`: [Telegram events](/en/telegram-api/como-funciona/eventos-do-webhooks).
</Note>

### Messages you send

| Event               | When it fires                                      | What to do with it            |
| ------------------- | -------------------------------------------------- | ----------------------------- |
| `message.sent`      | Message accepted and sent (gray ✓)                 | Mark as "sent" in your system |
| `message.delivered` | Delivered to the customer's device (gray ✓✓)       | Confirm delivery              |
| `message.read`      | Customer read or played media (blue ✓✓)            | Metrics, follow-up            |
| `message.clicked`   | Customer clicked a **short link** in the send      | Track campaign                |
| `message.failed`    | Could not send (invalid number, instance offline…) | Alert, retry, or cancel order |
| `message.deleted`   | Message deleted "for everyone"                     | Update history                |
| `message.edited`    | Text changed after send                            | Sync content                  |
| `message.updated`   | Any status change                                  | Generic status webhook        |
| `message.cancelled` | Scheduled send cancelled                           | Free slot / notify team       |
| `message.responded` | Customer **replied** quoting your message          | Support, conversational bot   |

### Messages you receive

| Event                      | When it fires                            | What to do with it                      |
| -------------------------- | ---------------------------------------- | --------------------------------------- |
| `whatsapp.received`        | **Someone sent you** a WhatsApp message  | Bot, ticket, CRM, most used for inbound |
| `whatsapp.inbound.edited`  | Customer **edited** a message you stored | Update conversation                     |
| `whatsapp.inbound.deleted` | Customer **deleted** a received message  | Remove or mark in history               |

<Info>
  Inbound only fires if enabled under **Settings → Received messages** (store and/or webhook). The legacy dashboard name `message.received` still works: the body uses `whatsapp.received`.
</Info>

### Instance (number connection)

| Event                   | When it fires                     | What to do with it                    |
| ----------------------- | --------------------------------- | ------------------------------------- |
| `instance.connecting`   | Waiting for code scan             | Show "scan the code"                  |
| `instance.qrcode`       | New code generated                | Display QR in your UI (`data.base64`) |
| `instance.connected`    | Number connected                  | Enable sends, notify team             |
| `instance.disconnected` | Disconnected (phone off, logout…) | Pause campaigns, alert NOC            |

The [Quick Start](/en/whatsapp-api/como-funciona/quick-start) refresh-code step can use this webhook instead of polling (`instance.qrcode`).

***

## Payload per event

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

<AccordionGroup>
  <Accordion title="message.sent">
    ```json theme={null}
    {
      "event": "message.sent",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:05:00.000Z",
      "data": {
        "to": "5511999999999",
        "type": "TEXT",
        "status": "SENT",
        "sentAt": "2025-02-20T14:05:00.000Z",
        "externalId": "3EB0xxxx"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.delivered">
    ```json theme={null}
    {
      "event": "message.delivered",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:05:30.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "DELIVERED"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.read">
    ```json theme={null}
    {
      "event": "message.read",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:06:00.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "READ"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.clicked">
    Fired on the **first** click on a short link in the send (workspace with short links enabled).

    ```json theme={null}
    {
      "event": "message.clicked",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:06:30.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "CLICKED",
        "clickedAt": "2025-02-20T14:06:30.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.failed">
    ```json theme={null}
    {
      "event": "message.failed",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:05:00.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "FAILED",
        "reason": "instance_disconnected"
      }
    }
    ```
  </Accordion>

  <Accordion title="whatsapp.received">
    ```json theme={null}
    {
      "event": "whatsapp.received",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:10:00.000Z",
      "data": {
        "persisted": true,
        "inboundId": "clxxinbound001",
        "from": "5511999999999",
        "bodyPreview": "Hi!",
        "remoteJid": "5511999999999@s.whatsapp.net",
        "isGroup": false,
        "externalMessageId": "3EB0xxxx",
        "matchedRuleIds": [],
        "persistDeniedReason": null,
        "storageCreditsCharged": 1,
        "storageCentsCharged": 0
      }
    }
    ```

    Extra fields may be added without breaking consumers.
  </Accordion>

  <Accordion title="message.responded">
    ```json theme={null}
    {
      "event": "message.responded",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:10:00.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "replyText": "Customer reply",
        "status": "RESPONDED"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.deleted">
    ```json theme={null}
    {
      "event": "message.deleted",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:07:00.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "DELETED",
        "source": "api"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.edited">
    ```json theme={null}
    {
      "event": "message.edited",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:08:00.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "EDITED",
        "newContent": "Corrected text"
      }
    }
    ```

    `newContent` may be `null` when unavailable.
  </Accordion>

  <Accordion title="message.updated">
    ```json theme={null}
    {
      "event": "message.updated",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:06:15.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "DELIVERED",
        "previousStatus": "SENT"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.cancelled">
    ```json theme={null}
    {
      "event": "message.cancelled",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "messageId": "clxxmessage789",
      "timestamp": "2025-02-20T14:04:00.000Z",
      "data": {
        "messageId": "clxxmessage789",
        "to": "5511999999999",
        "status": "CANCELLED"
      }
    }
    ```
  </Accordion>

  <Accordion title="whatsapp.inbound.edited">
    ```json theme={null}
    {
      "event": "whatsapp.inbound.edited",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:11:00.000Z",
      "data": {
        "inboundId": "clxxinbound001",
        "from": "5511999999999",
        "bodyPreview": "Hello! (edited)",
        "externalMessageId": "3EB0yyyy"
      }
    }
    ```
  </Accordion>

  <Accordion title="whatsapp.inbound.deleted">
    ```json theme={null}
    {
      "event": "whatsapp.inbound.deleted",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:12:00.000Z",
      "data": {
        "inboundId": "clxxinbound001",
        "from": "5511999999999",
        "externalMessageId": "3EB0yyyy"
      }
    }
    ```
  </Accordion>

  <Accordion title="instance.qrcode">
    ```json theme={null}
    {
      "event": "instance.qrcode",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:00:00.000Z",
      "data": {
        "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
      }
    }
    ```
  </Accordion>

  <Accordion title="instance.connected">
    ```json theme={null}
    {
      "event": "instance.connected",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:01:00.000Z",
      "data": {
        "phoneNumber": "5511999999999"
      }
    }
    ```

    `phoneNumber` may be `null` in some cases.
  </Accordion>

  <Accordion title="instance.disconnected">
    ```json theme={null}
    {
      "event": "instance.disconnected",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:02:00.000Z",
      "data": {}
    }
    ```
  </Accordion>

  <Accordion title="instance.connecting">
    ```json theme={null}
    {
      "event": "instance.connecting",
      "workspaceId": "clxxworkspace123",
      "instanceId": "clxxinstance456",
      "timestamp": "2025-02-20T14:00:00.000Z",
      "data": {
        "status": "AWAITING_QR",
        "message": "QR code generated; scan to connect"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

* [Quick Start](/en/whatsapp-api/como-funciona/quick-start): connect and send
* [API Key scopes](/en/whatsapp-api/como-funciona/escopos-api-key): permissions to read inbound
* [Webhooks (guide)](/en/guides/webhooks/index): create endpoint and test