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

> Sepa cuándo alguien entra o sale de la lista de no contactar, o cuándo un envío es bloqueado.

<Tip>
  En la API usted **pregunta**; en el webhook Notifique **avisa**. Ideal para sincronizar CRM, auditoría o alertas cuando un envío es bloqueado.
</Tip>

## En resumen

* Cada entrega es un **POST** `application/json` a la URL registrada.
* Tres eventos principales: entrada en la lista, salida de la lista y envío bloqueado.
* Responda **2xx rápido**; el procesamiento pesado va a cola en su lado.

Configuración general: [Webhooks](/es/guides/webhooks/index). Seguridad (HMAC): [Seguridad de webhooks](/es/guides/webhooks/seguranca).

***

## Cómo llega el 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         | Descripción                                    |
| ------------- | ---------------------------------------------- |
| `event`       | Nombre del evento (ej.: `suppression.added`)   |
| `workspaceId` | ID del workspace                               |
| `timestamp`   | ISO 8601                                       |
| `data`        | Detalles de la supresión o del envío bloqueado |

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

***

## Qué debe responder su servidor

| Respuesta               | Efecto                                    |
| ----------------------- | ----------------------------------------- |
| **2xx** en hasta \~10s  | Evento entregado; sale de la cola         |
| **4xx / 5xx / timeout** | Reintento automático (5 min, 30 min, 2 h) |

<Note>
  ¿Procesamiento lento? Responda **200** de inmediato y procese en segundo plano.
</Note>

***

## Referencia por evento

| Evento                | Cuándo dispara                                   | Qué hacer con esto                                                 |
| --------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
| `suppression.added`   | La identidad **pasa a estar** en la lista activa | Actualizar CRM, registrar auditoría                                |
| `suppression.removed` | La entrada **activa fue eliminada**              | Reactivar flujos de contacto en su sistema                         |
| `message.suppressed`  | Envío **bloqueado** por supresión                | Marcar intento como `RECIPIENT_SUPPRESSED`, no reintentar a ciegas |

<Info>
  Prefiera `message.suppressed` para todos los canales.
</Info>

La inclusión idempotente **no dispara** `suppression.added` duplicado para la misma identidad activa.

***

## 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">
    Se dispara cuando un envío individual o de campaña es bloqueado **antes de gastar crédito** o llamar al proveedor.

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

***

## Próximos pasos

* [Introducción](/es/suppressions-api/como-funciona/introducao): diferencia entre supresión y unsubscribe
* [Inicio rápido](/es/suppressions-api/como-funciona/quick-start): agregar y eliminar por API
* [Troubleshooting](/es/suppressions-api/como-funciona/troubleshooting): códigos de error