# Eventos

> Cómo llegan los eventos a tu webhook, el sobre y el catálogo de tipos.

## Cómo llega

Cada evento llega como un `POST` con cuerpo JSON a la URL que registraste como destino. Las cabeceras de cada entrega:

| Cabecera | Valor |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `Messajo-Webhooks/1` |
| `Messajo-Signature` | `t=<unix s>,v1=<hex>` — mira [Verificar la firma](/es/webhooks/verify-signature/) |
| `Messajo-Event-Id` | id del evento (`evt_…`), el mismo en todos los intentos y reenvíos |
| `Messajo-Event-Type` | tipo del evento, por ejemplo `message.received` |
| `Messajo-Delivery-Id` | id de esta entrega para este destino (`dlv_…`). Un reenvío crea una entrega nueva, con id nuevo |
| `Messajo-Delivery-Attempt` | número de intento de esta entrega, empezando en `1` |

Las cabeceras propias que registres en el destino también se envían. Nunca reemplazan a las `Messajo-*`, y `Host`, `Content-Type`, `Content-Length`, `User-Agent`, `Transfer-Encoding` y `Connection` no se pueden registrar.

## Sobre

Todo evento llega en el mismo sobre:

| Campo | Tipo | Qué es |
|---|---|---|
| `id` | `string` | id del evento (`evt_…`). Úsalo para descartar duplicados. |
| `type` | `string` | tipo del evento, por ejemplo `message.received`. |
| `format` | `"normalized"` \| `"meta"` | formato **usado** en `data` (mira abajo). |
| `org` | `string` | id de la organización. |
| `connection` | `string` \| `null` | id de la conexión (`conn_…`); `null` en eventos de la organización, como `destination.test`. |
| `channel` | `"whatsapp"` \| `"instagram"` \| `"messenger"` \| `null` | canal de la conexión; `null` cuando `connection` es `null`. |
| `timestamp` | `string` | fecha y hora del hecho, ISO 8601 en UTC. |
| `sequence` | `number` \| `null` | creciente por conversación; `null` en eventos fuera de una conversación (mira el [catálogo](#catálogo)). |
| `data` | `object` | el contenido del evento, en el formato que indica `format`. |

### Los dos formatos

Cada destino elige un formato:

- **`normalized`**: formato de Messajo, igual en todos los canales, en snake_case.
- **`meta`**: el trozo del webhook de Meta que generó el evento. En WhatsApp es el `value` del *change* reducido a este hecho: el array `messages` (o `statuses`, o `message_echoes`) con un solo elemento, y el `metadata` y el `contacts` correspondientes intactos. En Instagram y Messenger es el elemento de `messaging[]`.

Un evento que no nace de un webhook de Meta (por ejemplo `message.sent` y `destination.test`) no tiene versión `meta`: sale `normalized` incluso para un destino `meta`. Por eso el campo `format` dice el formato que se **usó**, no el que pidió el destino. Revisa `format` antes de leer `data`.

El mismo `message.received` en los dos formatos:

```json title="format: normalized"
{
  "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB",
  "type": "message.received",
  "format": "normalized",
  "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y",
  "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS",
  "channel": "whatsapp",
  "timestamp": "2026-11-09T14:03:27.000Z",
  "sequence": 42,
  "data": {
    "contact": {
      "display_name": "Maria",
      "id": "ctc_01JC9W3X5R1P0N9M8L7K6J5H4G",
      "identities": [{ "kind": "wa_id", "scope": "", "value": "5511999999999" }]
    },
    "conversation": {
      "extended_window_ends_at": null,
      "id": "cnv_01JC9W3X5S2Q1P0N9M8L7K6J5H",
      "window_ends_at": "2026-11-10T14:03:27.000Z"
    },
    "message": {
      "content": { "body": "¡Hola! ¿Ya salió mi pedido?", "type": "text" },
      "context": null,
      "direction": "inbound",
      "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA",
      "id": "msg_01JC9W3X6T3R2Q1P0N9M8L7K6J",
      "source": "customer",
      "timestamp": "2026-11-09T14:03:27.000Z"
    }
  }
}
```

```json title="format: meta"
{
  "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB",
  "type": "message.received",
  "format": "meta",
  "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y",
  "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS",
  "channel": "whatsapp",
  "timestamp": "2026-11-09T14:03:27.000Z",
  "sequence": 42,
  "data": {
    "contacts": [{ "profile": { "name": "Maria" }, "wa_id": "5511999999999" }],
    "messages": [
      {
        "from": "5511999999999",
        "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA",
        "text": { "body": "¡Hola! ¿Ya salió mi pedido?" },
        "timestamp": "1762697007",
        "type": "text"
      }
    ],
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "5511988887777", "phone_number_id": "106540352242922" }
  }
}
```

Las claves de `data` salen en orden alfabético y el mismo evento genera siempre los mismos bytes, en todos los intentos. Aun así, verifica la firma sobre el cuerpo crudo, nunca sobre un JSON re-serializado. La [referencia de la API](/es/reference) trae el schema completo de cada `data`.

## Catálogo

| Tipo | Cuándo | `sequence` | Canales |
|---|---|---|---|
| `message.received` | llegó un mensaje del contacto | sí | todos |
| `message.sent` | Meta aceptó un mensaje tuyo | sí | todos |
| `message.status` | cambió el estado de un mensaje tuyo (entregado, leído, fallido) | sí | todos |
| `message.echo` | mensaje enviado por fuera de la API (app del celular, Inbox de Meta) | sí | todos |
| `message.edited` | el contacto editó un mensaje | sí | todos |
| `message.revoked` | el contacto borró un mensaje | sí | todos |
| `call.incoming` | el contacto está llamando al número (con el `sdp` de la oferta) | sí | WhatsApp |
| `call.sdp_answer` | el contacto atendió una de tus [llamadas](/es/guides/calls/) (con el `sdp` de la respuesta) | sí | WhatsApp |
| `call.status` | la llamada cambió de estado (`RINGING`, `ACCEPTED`, `REJECTED`) | sí | WhatsApp |
| `call.ended` | la llamada terminó, con `end_reason` y la duración en `duration_s` | sí | WhatsApp |
| `call.permission_updated` | cambió el permiso de llamada del contacto (`status`, `expires_at`) | sí | WhatsApp |
| `group.created` · `group.create_failed` | Meta creó (o no) un [grupo](/es/guides/groups/) | `null` | WhatsApp |
| `group.settings_updated` · `group.participants_updated` · `group.join_requested` | cambiaron los datos o los participantes del grupo, o llegó una solicitud de ingreso | `null` | WhatsApp |
| `group.suspended` · `group.unsuspended` · `group.deleted` | el grupo fue suspendido, liberado o borrado | `null` | WhatsApp |
| `flow.response` | el contacto terminó un [Flow](/es/guides/flows/) (con `response` y `flow_token`) | sí | WhatsApp |
| `flow.status_changed` · `flow.endpoint_alert` · `flow.endpoint_error` | cambió el estado del Flow, Meta alertó sobre la salud del endpoint, o la app del contacto avisó un error | `null` | WhatsApp |
| `order.received` · `order.updated` | llegó un carrito o cambió un [pedido](/es/guides/commerce/) (cobro, estado, pago) | sí | WhatsApp |
| `payment.updated` | Meta avisó el pago de un pedido | sí | WhatsApp |
| `template.status` | Meta aprobó, rechazó o pausó una plantilla | `null` | WhatsApp |
| `connection.created` | nueva conexión activa | `null` | todos |
| `connection.updated` | cambió el estado (a activa, restringida o desactivada), el estado de salud o los datos de la conexión; el motivo llega en `reason` | `null` | todos |
| `connection.disconnected` | la conexión se apagó | `null` | todos |
| `connection.needs_reconnect` | se perdió el acceso y hay que rehacer la conexión | `null` | todos |
| `connection.error` | Meta avisó un error de la cuenta o del número, fuera de un mensaje (`errors[]`) | `null` | WhatsApp |
| `history.batch` | lote del historial de 6 meses importado en coexistencia | `null` | WhatsApp |
| `contacts.sync` | contactos sincronizados desde la app en coexistencia | `null` | WhatsApp |
| `comment.received` | llegó un comentario (o una respuesta a un comentario) en una publicación o directo de la cuenta | `null` | Instagram |
| `comment.replied` | respondiste un comentario en público | `null` | Instagram |
| `comment.private_replied` | enviaste una respuesta privada a un comentario (viene con el mensaje y el contacto) | `null` | Instagram |
| `comment.hidden` · `comment.unhidden` | ocultaste o volviste a mostrar un comentario | `null` | Instagram |
| `comment.deleted` | borraste un comentario | `null` | Instagram |
| `mention.received` | mencionaron la cuenta en un comentario, texto o historia (`source`) | `null` | Instagram |
| `publication.published` | salió una [publicación](/es/connect/instagram-content/#publicar), con `external_media_id` y `permalink` | `null` | Instagram |
| `publication.failed` | una publicación falló, con el motivo en `publication.error` | `null` | Instagram |
| `campaign.scheduled` · `campaign.started` · `campaign.completed` · `campaign.canceled` | una [campaña](/es/guides/campaigns/) se programó, empezó, terminó o se canceló (`data.campaign` con estado y números) | `null` | WhatsApp |
| `campaign.paused` · `campaign.resumed` | la campaña se pausó o volvió; `reason` dice el motivo y `auto: true` cuando fue Messajo (incluido `limit_reached`, el nivel de 24 h, y `org_suspended`, cuando la organización se suspende) | `null` | WhatsApp |
| `campaign.progress` | cambiaron los números de la campaña (como máximo 1 por minuto) | `null` | WhatsApp |
| `org.standing_changed` | cambió la situación de la organización (`active`, `restricted` o `suspended`), desde la `1.1.0` | `null` | — |
| `destination.test` | hiciste clic en **Probar** en el destino (o llamaste a `POST /v1/destinations/{id}/test`) | `null` | — |

Atender, rechazar, terminar y hacer llamadas por la API: ver [Llamadas en WhatsApp](/es/guides/calls/).

`message.sent` y `message.status` traen `campaign: { id, recipient_id }` cuando el mensaje salió de una campaña, y `null` en los demás casos. Los eventos `message.*` traen `group: { id, external_id, subject }` en un mensaje de grupo (y `null` fuera de él) y el tipo de conversación en `conversation.kind`.

`message.status` trae `cost: { estimate, currency, rate_card_version }` en el estado que generó cobro de Meta y `null` en los demás; consulta [Costos de Meta](/es/guides/costs/).

### Organización

`org.standing_changed` avisa cuando cambia la situación de la organización. `reason` es `payment`, `abuse`, `manual` o `meta_request`, y viene `null` cuando la organización vuelve a `active`.

```json
{
  "type": "org.standing_changed",
  "data": {
    "organization": {
      "id": "org_1",
      "standing": "suspended",
      "previous_standing": "restricted",
      "reason": "payment",
      "since": "2026-11-13T12:00:00.000Z"
    }
  }
}
```

- Se emite **antes** de que los webhooks de la organización queden retenidos y nunca se retiene: siempre recibes el aviso de la suspensión.
- Mientras la organización está suspendida, las entregas quedan con estado `held`. Al volver, salen en el orden de creación del evento (orden de encolado); dentro de una conversación vale la `sequence`.
- Una entrega `held` con más de **15 días** pasa a `failed` con el error `org_suspended`.

### Eventos de WABA y de organización

Dos grupos de eventos no pertenecen a una sola conexión:

- **Eventos de WABA** (`template.*`, `flow.status_changed`, `flow.endpoint_alert` y `flow.endpoint_error`; no `flow.response`, que es del número que lo recibió): Meta los emite para la cuenta de WhatsApp Business (WABA), que puede tener varios números. Messajo entrega el evento a un destino de **cualquier conexión de la misma WABA**, una vez por destino. El destino global también lo recibe, sin duplicados.
- **Eventos de organización** (`org.*`, como `org.standing_changed`): no tienen conexión, así que solo llegan a **destinos globales** cuyo filtro los incluya (`org.*` o `*`). Un destino de conexión nunca los recibe.

### Motivos de la conexión

Los eventos `connection.*` traen la conexión en `data.connection`, con `status`, `previous_status` y el motivo en `reason`:

| `reason` | Estado después | Qué pasó |
|---|---|---|
| `reconnected` | activa | La conexión se rehízo (desde el panel, por enlace o porque Meta reconectó la cuenta) |
| `reinstated` | activa | Meta reactivó la cuenta después de una violación o baneo |
| `restriction_lifted` | activa | Terminó la restricción de Meta |
| `account_restriction` | restringida | Meta restringió la cuenta por un plazo |
| `policy_blocked` | restringida | Meta bloqueó un envío por política (`368` o `131031`) |
| `violation:<tipo>` | desactivada | Meta señaló una violación de política |
| `banned` | desactivada | Meta baneó la cuenta |
| `token_invalid` · `meta_token_invalid` | necesita reconectar | Meta invalidó el token (error `190`), en una lectura de estado o en un envío |
| `partner_removed` · `partner_removed:<motivo>` | desconectada | La cuenta quitó a Messajo como socio |
| `app_uninstalled` | desconectada | La app se desinstaló de la cuenta |
| `account_deleted` | desconectada | La cuenta o el número se eliminó en Meta |
| `offboarded` | desconectada | La cuenta salió de la plataforma de Meta |
| `user_requested` | desconectada | Alguien de la organización la desconectó desde el panel o por la API |
| `billing_suspended` | desconectada | La organización se suspendió por falta de pago y sus conexiones fueron desconectadas |
| `token_expired` | necesita reconectar | Legado: ya no se emite (el error 190 ahora pasa a `token_invalid`) |
| `app_deauthorized` | desconectada (Instagram) · necesita reconectar (Messenger) | La persona que autorizó quitó la app en la configuración de Meta |
| `data_deleted` | desconectada | La persona pidió a Meta borrar sus datos y Messajo borró los datos de la cuenta de Instagram |
| `scheduled_for_disable` | sin cambio | Meta programó la desactivación de la cuenta |
| `quality_changed` | sin cambio | Cambió la calidad del número |
| `limit_changed` | sin cambio | Cambió el nivel de envío o la capacidad de la cuenta |
| `send_rate_changed` | sin cambio | Cambió la velocidad (20, 80 o 1.000 msg/s) |
| `can_send_changed` | sin cambio | Cambió el **Envío** (disponible, limitado o bloqueado) |
| `name_approved` · `name_rejected` | sin cambio | Meta decidió el pedido de cambio del nombre visible |
| `alert` | sin cambio | Meta envió una alerta de la cuenta |
| `dm_access_disabled` | sin cambio | La cuenta de Instagram desactivó el acceso a los mensajes fuera de la app (detectado al conectar o por el health check) |
| `resubscribed` | sin cambio | La app había salido de la suscripción de webhooks de la cuenta o Página y Messajo la suscribió de nuevo |
| `policy_enforcement` | restringida o activa | Meta bloqueó o liberó la Página en Messenger por política |

Cuando el estado no cambia, `previous_status` es igual a `status`. Un cambio de estado también envía un correo a dueños y admins (como máximo uno por motivo cada 6 h).

## Orden y duplicados

- La entrega es **al menos una vez**: el mismo evento puede llegar más de una vez. Deduplica por `Messajo-Event-Id` (igual al `id` del sobre).
- Los eventos pueden llegar desordenados, también entre entregas y reenvíos. Dentro de una conversación, ordena por `sequence`: solo crece.
- Responde `2xx` rápido y procesa después (en una cola tuya). Trabajo pesado dentro de la petición hace que la entrega agote el tiempo y vuelva como reintento.

## Reintentos y fallos

- **Éxito** = respuesta `2xx` en hasta **10 segundos**, en total. Cualquier otra cosa cuenta como fallo: otro estado, tiempo agotado, error de red o dirección bloqueada. Las redirecciones (`3xx`) **no** se siguen y cuentan como fallo.
- Messajo guarda los primeros 1024 bytes de la respuesta de cada intento, para que los veas en el panel.
- Después de un fallo, reintenta según la tabla de abajo: 1 intento inmediato y 14 más, a lo largo de poco más de 23 horas. Cada espera varía ±10% y ningún intento sale después de 24 horas desde la creación de la entrega.

| Intento | Espera desde el anterior | Desde el 1.º (aprox.) |
|---|---|---|
| 1 | — | 0 |
| 2 | 10 s | 10 s |
| 3 | 30 s | 40 s |
| 4 | 1 min | 1 min 40 s |
| 5 | 2 min | 3 min 40 s |
| 6 | 5 min | 8 min 40 s |
| 7 | 10 min | 18 min 40 s |
| 8 | 20 min | 38 min 40 s |
| 9 | 40 min | 1 h 18 min |
| 10 | 1 h | 2 h 18 min |
| 11 | 2 h | 4 h 18 min |
| 12 | 3 h | 7 h 18 min |
| 13 | 4 h | 11 h 18 min |
| 14 | 6 h | 17 h 18 min |
| 15 | 6 h | 23 h 18 min |

### Lista de fallos y reenvío

- Agotados los intentos, la entrega queda `failed` y entra en la **lista de fallos** del destino, en el panel.
- **Reenviar** crea una entrega nueva del mismo evento (mismo `Messajo-Event-Id`, nuevo `Messajo-Delivery-Id`, intento `1`). Solo funciona con el destino activo.
- Para reenviar varias a la vez, usa **Reenviar fallos** en el panel o `POST /v1/destinations/{id}/redeliver-failed` con `since` (y `until`, opcional). Cada llamada pone en cola hasta 1000 fallos y devuelve `{ queued, has_more }`: con `has_more: true`, llama de nuevo.
- Las entregas y los eventos se guardan durante **30 días**.

### Pausa automática

- Un destino se pausa solo (`auto_paused`) cuando acumula **10 fallos seguidos** y lleva fallando **al menos 24 horas**. Cualquier `2xx` reinicia la cuenta.
- Al pausarse, las entregas todavía en curso de ese destino pasan a `failed` con el error `destination_paused`, y los dueños y admins de la organización reciben un **correo**.
- Mientras el destino esté pausado (solo o por ti), cada evento nuevo genera una entrega `failed` con `destination_paused`. No se pierde nada: después de corregir el endpoint y **reanudar** el destino, reenvía los fallos del periodo.

## Filtros

Cada destino recibe solo lo que elijas:

- **por evento**: una lista de patrones. Vale `*` (todo), `<familia>.*` (por ejemplo `message.*` o `connection.*`) y el tipo exacto (por ejemplo `message.status`). Un patrón que no es un tipo conocido ni una familia conocida o reservada se rechaza con `validation_failed`;
- **por conexión**: un destino de conexión recibe solo los eventos de ella; un destino global (sin conexión) recibe los de todas. Mira [Tipos de destino](/es/webhooks/destinations/#global-o-por-conexión);
- **formato**: `normalized` o `meta`.

El evento llega cuando algún patrón coincide con el tipo **y** el destino acepta la conexión del evento. El `destination.test` no pasa por los filtros: va solo al destino probado, en un único intento, incluso con el destino pausado.

## Otros destinos

El webhook es el destino por defecto. RabbitMQ, SQS, Kafka y WebSocket reciben el mismo sobre, con la misma firma, los mismos filtros y los mismos reintentos: consulta [Tipos de destino](/es/webhooks/destinations/).
