Ir al contenido

Webhooks

Eventos

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

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

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).
data object el contenido del evento, en el formato que indica format.

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:

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"
}
}
}
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 trae el schema completo de cada data.

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 (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 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 (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 (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, 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 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.

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.

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.

{
"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.

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.

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).

  • 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.
  • É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
  • 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.
  • 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.

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;
  • 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.

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.