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

> Reciba notificaciones en su servidor cuando el estado del mensaje cambie, alguien responda o la instancia se conecte.

<Tip>
  Con la API usted **pregunta**; con webhooks Notifique **te lo dice**. Al igual que una aplicación bancaria empuja cuando llega una transferencia, su backend no necesita hacer sondeo cada segundo.
</Tip>

## En breve

* Cada entrega es un **POST** `application/json` a la URL que registraste.
* Los eventos `message.*` e `instance.*` son **solo WhatsApp** (Telegram usa `telegram.*`).
* Habilite **solo** los eventos que su integración necesita.
* Responda **2xx rápidamente**; el trabajo pesado va a una cola de tu lado.

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

***

## Cómo se ve el POST

Sobre estándar para cada evento:

| Campo         | Descripción                               |
| ------------- | ----------------------------------------- |
| `event`       | Nombre del evento (ej. `message.sent`)    |
| `workspaceId` | ID del espacio de trabajo                 |
| `instanceId`  | ID de instancia WhatsApp                  |
| `messageId`   | ID del mensaje saliente (cuando aplique)  |
| `timestamp`   | ISO 8601, use para anti-replay            |
| `data`        | Campos específicos del evento (camelCase) |

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

***

## Qué debe devolver tu servidor

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

<Note>
  ¿Procesamiento lento? Devuelva **200** inmediatamente y procese en segundo plano. Tardar más de 10 segundos cuenta como timeout y es posible que el evento se reenvíe.
</Note>

Valide `X-Notifique-Signature` y una marca de tiempo reciente. Detalles: [Seguridad de webhooks](/es/guides/webhooks/seguranca).

***

## Referencia de eventos

Use estos eventos al integrar **bots, soporte, ERP o automatización** en WhatsApp.

<Note>
  Los nombres `message.*` son **solo WhatsApp**. Telegram usa `telegram.*`: [Eventos de Telegram](/es/telegram-api/como-funciona/eventos-do-webhooks).
</Note>

### Mensajes que envías

| Evento              | Cuándo se dispara                                       | Qué hacer con ello                    |
| ------------------- | ------------------------------------------------------- | ------------------------------------- |
| `message.sent`      | Mensaje aceptado y enviado (✓ gris)                     | Marcar como "enviado" en su sistema   |
| `message.delivered` | Entregado al dispositivo del cliente (✓✓ gris)          | Confirmar entrega                     |
| `message.read`      | Cliente leyó o reprodujo medio (✓✓ azul)                | Métricas, seguimiento                 |
| `message.clicked`   | Cliente hizo clic en un **enlace corto** del envío      | Seguir campaña                        |
| `message.failed`    | No se pudo enviar (número inválido, instancia offline…) | Alertar, reintentar o cancelar pedido |
| `message.deleted`   | Mensaje eliminado "para todos"                          | Actualizar historial                  |
| `message.edited`    | Texto cambiado después del envío                        | Sincronizar contenido                 |
| `message.updated`   | Cualquier cambio de estado                              | Webhook genérico de estado            |
| `message.cancelled` | Envío programado cancelado                              | Liberar slot / avisar al equipo       |
| `message.responded` | Cliente **respondió** citando su mensaje                | Soporte, bot conversacional           |

### Mensajes que recibes

| Evento                     | Cuándo se dispara                            | Qué hacer con ello                            |
| -------------------------- | -------------------------------------------- | --------------------------------------------- |
| `whatsapp.received`        | **Alguien te envió** un mensaje WhatsApp     | Bot, ticket, CRM, el más usado para entrantes |
| `whatsapp.inbound.edited`  | Cliente **editó** un mensaje que almacenaste | Actualizar conversación                       |
| `whatsapp.inbound.deleted` | Cliente **eliminó** un mensaje recibido      | Quitar o marcar en historial                  |

<Info>
  El mensaje entrante solo se activa si está habilitado en **Configuración → Mensajes recibidos** (almacenamiento y/o webhook). El nombre heredado del panel `message.received` todavía funciona: el cuerpo usa `whatsapp.received`.
</Info>

### Instancia (conexión del número)

| Evento                  | Cuándo se dispara                        | Qué hacer con ello                  |
| ----------------------- | ---------------------------------------- | ----------------------------------- |
| `instance.connecting`   | Esperando escaneo del código             | Mostrar "escanea el código"         |
| `instance.qrcode`       | Nuevo código generado                    | Mostrar QR en tu UI (`data.base64`) |
| `instance.connected`    | Número conectado                         | Habilitar envíos, avisar al equipo  |
| `instance.disconnected` | Desconectado (teléfono apagado, logout…) | Pausar campañas, alertar NOC        |

El paso de actualizar código del [Inicio rápido](/es/whatsapp-api/como-funciona/quick-start) puede usar este webhook en lugar de sondeo (`instance.qrcode`).

***

## Carga útil por evento

Cuerpo POST **completo**. El sobre (`event`, ids, `timestamp`) coincide con el ejemplo anterior; abajo cambia lo que va en `data`.

<AccordionGroup>
  <Accordion title="message.sent" />

  <Accordion title="message.delivered" />

  <Accordion title="message.read" />

  <Accordion title="message.clicked">
    Se activa en el **primer** clic en un enlace corto en el envío (espacio de trabajo con enlaces cortos habilitados).
  </Accordion>

  <Accordion title="message.failed" />

  <Accordion title="whatsapp.received">
    Pueden añadirse campos extra sin romper consumidores.
  </Accordion>

  <Accordion title="message.responded" />

  <Accordion title="message.deleted" />

  <Accordion title="message.edited">
    `newContent` puede ser `null` cuando no esté disponible.
  </Accordion>

  <Accordion title="message.updated" />

  <Accordion title="message.cancelled" />

  <Accordion title="whatsapp.inbound.edited" />

  <Accordion title="whatsapp.inbound.deleted" />

  <Accordion title="instance.qrcode" />

  <Accordion title="instance.connected">
    `phoneNumber` puede ser `null` en algunos casos.
  </Accordion>

  <Accordion title="instance.disconnected" />

  <Accordion title="instance.connecting" />
</AccordionGroup>

***

## Próximos pasos

* [Inicio rápido](/es/whatsapp-api/como-funciona/quick-start): conectar y enviar
* [Ámbitos de clave API](/es/whatsapp-api/como-funciona/escopos-api-key): permisos para leer entrantes
* [Webhooks (guía)](/es/guides/webhooks/index): crear endpoint y probar