> ## 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 o e-mail for enviado, entregue, aberto, clicado, falhar ou for marcado como spam.

<Tip>
  Na API você **pergunta**; no webhook a Notifique **avisa**. Ideal para marcar pedido como entregue, medir abertura ou suprimir quem reclamou spam, sem polling.
</Tip>

## Em poucas palavras

* Toda entrega é um **POST** `application/json` para a URL cadastrada.
* Eventos `email.*` são **só e-mail**, WhatsApp usa `message.*`, SMS usa `sms.*`.
* `instanceId` vem **vazio** (e-mail não usa instância).
* Ative **só** os eventos que sua integração usa.
* Responda **2xx rápido**; processamento 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

```json theme={null}
{
  "event": "email.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}
```

| Campo         | Descrição                                                 |
| ------------- | --------------------------------------------------------- |
| `event`       | Nome do evento (ex.: `email.delivered`)                   |
| `workspaceId` | ID do workspace                                           |
| `instanceId`  | Sempre vazio no e-mail                                    |
| `timestamp`   | ISO 8601, use para anti-replay                            |
| `data`        | Campos do envio (`emailId`, `to`, `from`, `status`, etc.) |

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

***

## 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. Acima de \~10 s 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 **e-commerce, ERP ou automação** com e-mail.

### Envio e engajamento

| Evento             | Quando dispara                                   | O que fazer com isso     |
| ------------------ | ------------------------------------------------ | ------------------------ |
| `email.sent`       | E-mail aceito e enviado                          | Marcar como enviado      |
| `email.delivered`  | Provedor confirmou entrega na caixa              | Confirmar inbox          |
| `email.opened`     | Destinatário abriu (primeira abertura rastreada) | Engajamento, lead quente |
| `email.clicked`    | Clique em link rastreado do e-mail               | Conversão, funil         |
| `email.failed`     | Bounce ou erro de envio                          | Limpar lista, alertar    |
| `email.complained` | Marcado como spam                                | Suprimir endereço        |
| `email.cancelled`  | Agendamento cancelado antes do envio             | Atualizar campanha       |

***

## Payload de cada evento

Corpo completo do POST. O envelope (`event`, ids, `timestamp`) segue o exemplo acima; abaixo, o que muda em `data`.

<AccordionGroup>
  <Accordion title="email.sent">
    ```json theme={null}
    {
      "event": "email.sent",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:29:00.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "subject": "Confirmação de pedido",
        "status": "SENT",
        "sentAt": "2025-02-10T14:29:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="email.delivered">
    ```json theme={null}
    {
      "event": "email.delivered",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:30:00.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "status": "DELIVERED",
        "deliveredAt": "2025-02-10T14:30:05.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="email.opened">
    Disparado na **primeira** abertura rastreada deste envio.

    ```json theme={null}
    {
      "event": "email.opened",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:35:00.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "status": "OPENED",
        "openedAt": "2025-02-10T14:35:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="email.clicked">
    Disparado no **primeiro** clique em link rastreado deste envio (ou link curto atribuído).

    ```json theme={null}
    {
      "event": "email.clicked",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:36:00.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "status": "CLICKED",
        "clickedAt": "2025-02-10T14:36:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="email.failed">
    ```json theme={null}
    {
      "event": "email.failed",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:29:30.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "status": "FAILED",
        "failedAt": "2025-02-10T14:29:30.000Z",
        "errorMessage": "bounce_hard"
      }
    }
    ```
  </Accordion>

  <Accordion title="email.complained">
    Boa prática: incluir o `to` em lista de supressão ao receber este evento.

    ```json theme={null}
    {
      "event": "email.complained",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T15:00:00.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "status": "COMPLAINED",
        "complainedAt": "2025-02-10T15:00:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="email.cancelled">
    ```json theme={null}
    {
      "event": "email.cancelled",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T12:00:00.000Z",
      "data": {
        "emailId": "clxx456...",
        "to": "cliente@example.com",
        "from": "noreply@seudominio.com",
        "status": "CANCELLED"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Próximos passos

* [Quick Start](/emails-api/como-funciona/quick-start): primeiro envio
* [Introdução](/emails-api/como-funciona/introducao): ciclo de status
* [Escopos](/emails-api/como-funciona/escopos-da-api-key): permissões da chave
* [Webhooks (guia geral)](/guides/webhooks/index)