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

> Know when someone enters or leaves the do-not-contact list, or when a send is blocked.

<Tip>
  In the API you **ask**; with webhooks Notifique **notifies you**. Ideal for syncing CRM, audit trails, or alerts when a send is blocked.
</Tip>

## In brief

* Every delivery is a **POST** `application/json` to your registered URL.
* Three main events: list entry, list removal, and blocked send.
* Respond **2xx quickly**; heavy processing goes to a queue on your side.

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

***

## How the POST arrives

```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..."
  }
}
```

| Field         | Description                           |
| ------------- | ------------------------------------- |
| `event`       | Event name (e.g. `suppression.added`) |
| `workspaceId` | Workspace ID                          |
| `timestamp`   | ISO 8601                              |
| `data`        | Suppression or blocked-send details   |

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

***

## What your server should respond

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

<Note>
  Slow processing? Respond **200** right away and process in the background.
</Note>

***

## Event reference

| Event                 | When it fires                           | What to do with it                                           |
| --------------------- | --------------------------------------- | ------------------------------------------------------------ |
| `suppression.added`   | Identity **becomes active** on the list | Update CRM, log audit trail                                  |
| `suppression.removed` | Active entry **was removed**            | Re-enable contact flows in your system                       |
| `message.suppressed`  | Send **blocked** by suppression         | Mark attempt as `RECIPIENT_SUPPRESSED`, do not retry blindly |

<Info>
  Prefer `message.suppressed` for all channels.
</Info>

Idempotent addition does **not fire** duplicate `suppression.added` for the same active identity.

***

## Payload per event

<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">
    Fired when an individual or campaign send is blocked **before spending credit** or calling the provider.

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

***

## Next steps

* [Introduction](/en/suppressions-api/como-funciona/introducao): difference between suppression and unsubscribe
* [Quick Start](/en/suppressions-api/como-funciona/quick-start): add and remove via API
* [Troubleshooting](/en/suppressions-api/como-funciona/troubleshooting): error codes