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

> Saiba quando alguém entra ou sai da lista de não contatar, ou quando um envio é bloqueado.

<Tip>
  Na API você **pergunta**; no webhook a Notifique **avisa**. Ideal para sincronizar CRM, auditoria ou alertas quando um envio é barrado.
</Tip>

## Em poucas palavras

* Toda entrega é um **POST** `application/json` para a URL cadastrada.
* Três eventos principais: entrada na lista, saída da lista e envio bloqueado.
* Responda **2xx rápido**; processamento pesado vai para fila no seu lado.

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

***

## Como vem o POST

```json theme={null}
{
  "event": "suppression.added",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-08-01T10:00:00.000Z",
  "data": {
    "suppressionId": "clsup456...",
    "type": "phone",
    "value": "+5511999990000",
    "reason": "opt_out",
    "origin": "system",
    "channels": ["sms", "whatsapp", "rcs", "voice"],
    "contactId": "clcontact789..."
  }
}
```

| Campo         | Descrição                                   |
| ------------- | ------------------------------------------- |
| `event`       | Nome do evento (ex.: `suppression.added`)   |
| `workspaceId` | ID do workspace                             |
| `timestamp`   | ISO 8601                                    |
| `data`        | Detalhes da supressão ou do envio bloqueado |

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.
</Note>

***

## Referência por evento

| Evento                | Quando dispara                              | O que fazer com isso                                             |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| `suppression.added`   | Identidade **passa a estar** na lista ativa | Atualizar CRM, registrar auditoria                               |
| `suppression.removed` | Entrada **ativa foi removida**              | Reativar fluxos de contato no seu sistema                        |
| `message.suppressed`  | Envio **bloqueado** por supressão           | Marcar tentativa como `RECIPIENT_SUPPRESSED`, não retentar à toa |

<Info>
  Prefira `message.suppressed` para todos os canais.
</Info>

Inclusão idempotente **não dispara** `suppression.added` duplicado para a mesma identidade ativa.

***

## Payload de cada evento

<AccordionGroup>
  <Accordion title="suppression.added">
    ```json theme={null}
    {
      "event": "suppression.added",
      "data": {
        "suppressionId": "clsup456...",
        "type": "email",
        "value": "cliente@example.com",
        "reason": "bounce",
        "origin": "provider",
        "channels": ["email"],
        "contactId": null
      }
    }
    ```
  </Accordion>

  <Accordion title="suppression.removed">
    ```json theme={null}
    {
      "event": "suppression.removed",
      "data": {
        "suppressionId": "clsup456...",
        "type": "phone",
        "value": "+5511999990000",
        "reason": "manual",
        "origin": "api"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.suppressed">
    Disparado quando um envio individual ou de campanha é barrado **antes de gastar crédito** ou chamar o provedor.

    ```json theme={null}
    {
      "event": "message.suppressed",
      "data": {
        "messageId": "clmsg123...",
        "type": "phone",
        "value": "+5511999990000",
        "channel": "whatsapp",
        "code": "RECIPIENT_SUPPRESSED",
        "suppressionId": "clsup456..."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Próximos passos

* [Introdução](/suppressions-api/como-funciona/introducao): diferença entre supressão e unsubscribe
* [Quick Start](/suppressions-api/como-funciona/quick-start): adicionar e remover pela API
* [Troubleshooting](/suppressions-api/como-funciona/troubleshooting): códigos de erro