> ## 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.

# Eventos dos Webhooks

> Receba no seu servidor quando uma mensagem muda de status, alguém responde ou a instância conecta.

<Tip>
  Na API você **pergunta**; no webhook a Notifique **avisa**. É como o app do banco mandando push quando o PIX cai, seu backend não precisa ficar consultando a cada segundo.
</Tip>

## Em poucas palavras

* Toda entrega é um **POST** `application/json` para a URL que você cadastrou.
* Eventos `message.*` e `instance.*` são **só WhatsApp** (Telegram usa `telegram.*`).
* Ative **só** os eventos que sua integração usa.
* Responda **2xx rápido**; trabalho pesado vai para fila no seu lado.

Configuração geral: [Webhooks](/guides/webhooks/index). Segurança (assinatura HMAC): [Segurança de webhooks](/guides/webhooks/seguranca).

***

## Como vem o POST

Estrutura padrão em todos os eventos:

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

| Campo         | Descrição                                 |
| ------------- | ----------------------------------------- |
| `event`       | Nome do evento (ex.: `message.sent`)      |
| `workspaceId` | ID do workspace                           |
| `instanceId`  | ID da instância WhatsApp                  |
| `messageId`   | ID da mensagem enviada (quando aplicável) |
| `timestamp`   | ISO 8601, use para anti-replay            |
| `data`        | Campos específicos do evento (camelCase)  |

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

***

## O que seu servidor deve responder

| Resposta                | Efeito                                      |
| ----------------------- | ------------------------------------------- |
| **2xx** em até \~10s    | Evento entregue; sai da fila                |
| **4xx / 5xx / timeout** | Retentativa automática (5 min, 30 min, 2 h) |

<Note>
  Processamento demorado? Responda **200** logo e processe em background. Demorar mais de 10 segundos conta como timeout e o evento pode ser reenviado.
</Note>

Valide `X-Notifique-Signature` e timestamp recente. Detalhes: [Segurança de webhooks](/guides/webhooks/seguranca).

***

## Referência por evento

Use estes eventos ao integrar **bot, atendimento, ERP ou automação** no WhatsApp.

<Note>
  Os nomes `message.*` são **só WhatsApp**. Telegram usa `telegram.*`: [eventos Telegram](/telegram-api/como-funciona/eventos-do-webhooks).
</Note>

### Mensagens que você envia

| Evento              | Quando dispara                                        | O que fazer com isso                 |
| ------------------- | ----------------------------------------------------- | ------------------------------------ |
| `message.sent`      | Mensagem aceita e enviada (✓ cinza)                   | Marcar como “enviado” no seu sistema |
| `message.delivered` | Chegou no aparelho do cliente (✓✓ cinza)              | Confirmar entrega                    |
| `message.read`      | Cliente leu ou ouviu (✓✓ azul)                        | Métricas, follow-up                  |
| `message.clicked`   | Cliente clicou em **link curto** do envio             | Rastrear campanha                    |
| `message.failed`    | Não deu para enviar (número inválido, instância off…) | Alertar, retentar ou cancelar pedido |
| `message.deleted`   | Mensagem apagada “para todos”                         | Atualizar histórico                  |
| `message.edited`    | Texto alterado após envio                             | Sincronizar conteúdo                 |
| `message.updated`   | Qualquer mudança de status                            | Webhook genérico de status           |
| `message.cancelled` | Agendamento cancelado                                 | Liberar slot / avisar equipe         |
| `message.responded` | Cliente **respondeu** citando sua mensagem            | Atendimento, bot conversacional      |

### Mensagens que você recebe

| Evento                     | Quando dispara                          | O que fazer com isso                        |
| -------------------------- | --------------------------------------- | ------------------------------------------- |
| `whatsapp.received`        | **Alguém te mandou** WhatsApp           | Bot, ticket, CRM, o mais usado para inbound |
| `whatsapp.inbound.edited`  | Cliente **editou** msg que você guardou | Atualizar conversa                          |
| `whatsapp.inbound.deleted` | Cliente **apagou** msg recebida         | Remover ou marcar no histórico              |

<Info>
  Inbound só dispara se estiver ligado em **Settings → Received messages** (guardar e/ou webhook). O nome antigo `message.received` no painel ainda funciona: o corpo vem como `whatsapp.received`.
</Info>

### Instância (conexão do número)

| Evento                  | Quando dispara                     | O que fazer com isso                |
| ----------------------- | ---------------------------------- | ----------------------------------- |
| `instance.connecting`   | Aguardando escaneamento do código  | Mostrar “escaneie o código”         |
| `instance.qrcode`       | Novo código gerado                 | Exibir QR na sua UI (`data.base64`) |
| `instance.connected`    | Número conectou                    | Liberar envios, avisar equipe       |
| `instance.disconnected` | Desconectou (celular off, logout…) | Pausar campanhas, alertar NOC       |

No [Quick Start](/whatsapp-api/como-funciona/quick-start), renovar código pode usar este webhook em vez de polling (`instance.qrcode`).

***

## Payload de cada evento

Corpo completo (**body**) do POST. O envelope (`event`, ids, `timestamp`) é igual ao exemplo acima; abaixo, o que muda em `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">
    Disparado no **primeiro** clique em link curto do envio (workspace com links curtos ligados).

    ```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": "Olá!",
        "remoteJid": "5511999999999@s.whatsapp.net",
        "isGroup": false,
        "externalMessageId": "3EB0xxxx",
        "matchedRuleIds": [],
        "persistDeniedReason": null,
        "storageCreditsCharged": 1,
        "storageCentsCharged": 0
      }
    }
    ```

    Campos extras podem ser adicionados sem quebrar consumidores.
  </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": "Resposta do destinatário",
        "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": "Texto corrigido"
      }
    }
    ```

    `newContent` pode ser `null` quando não disponível.
  </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": "Olá! (editado)",
        "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` pode ser `null` em alguns casos.
  </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>

***

## Próximos passos

* [Quick Start](/whatsapp-api/como-funciona/quick-start): conectar e enviar
* [Escopos da API Key](/whatsapp-api/como-funciona/escopos-api-key): permissões para ler inbound
* [Webhooks (guia)](/guides/webhooks/index): criar endpoint e testar