Webhooks
Eventos
Cómo llegan los eventos a tu webhook, el sobre y el catálogo de tipos.
Cómo llega
Sección titulada «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 |
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. |
Los dos formatos
Sección titulada «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 elvaluedel change reducido a este hecho: el arraymessages(ostatuses, omessage_echoes) con un solo elemento, y elmetadatay elcontactscorrespondientes intactos. En Instagram y Messenger es el elemento demessaging[].
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:
{ "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" } }}{ "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.
Catálogo
Sección titulada «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í | |
call.sdp_answer |
el contacto atendió una de tus llamadas (con el sdp de la respuesta) |
sí | |
call.status |
la llamada cambió de estado (RINGING, ACCEPTED, REJECTED) |
sí | |
call.ended |
la llamada terminó, con end_reason y la duración en duration_s |
sí | |
call.permission_updated |
cambió el permiso de llamada del contacto (status, expires_at) |
sí | |
group.created · group.create_failed |
Meta creó (o no) un grupo | null |
|
group.settings_updated · group.participants_updated · group.join_requested |
cambiaron los datos o los participantes del grupo, o llegó una solicitud de ingreso | null |
|
group.suspended · group.unsuspended · group.deleted |
el grupo fue suspendido, liberado o borrado | null |
|
flow.response |
el contacto terminó un Flow (con response y flow_token) |
sí | |
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 |
|
order.received · order.updated |
llegó un carrito o cambió un pedido (cobro, estado, pago) | sí | |
payment.updated |
Meta avisó el pago de un pedido | sí | |
template.status |
Meta aprobó, rechazó o pausó una plantilla | null |
|
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 |
|
history.batch |
lote del historial de 6 meses importado en coexistencia | null |
|
contacts.sync |
contactos sincronizados desde la app en coexistencia | null |
|
comment.received |
llegó un comentario (o una respuesta a un comentario) en una publicación o directo de la cuenta | null |
|
comment.replied |
respondiste un comentario en público | null |
|
comment.private_replied |
enviaste una respuesta privada a un comentario (viene con el mensaje y el contacto) | null |
|
comment.hidden · comment.unhidden |
ocultaste o volviste a mostrar un comentario | null |
|
comment.deleted |
borraste un comentario | null |
|
mention.received |
mencionaron la cuenta en un comentario, texto o historia (source) |
null |
|
publication.published |
salió una publicación, con external_media_id y permalink |
null |
|
publication.failed |
una publicación falló, con el motivo en publication.error |
null |
|
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 |
|
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 |
|
campaign.progress |
cambiaron los números de la campaña (como máximo 1 por minuto) | null |
|
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.
Organización
Sección titulada «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.
{ "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 lasequence. - Una entrega
heldcon más de 15 días pasa afailedcon el errororg_suspended.
Eventos de WABA y de organización
Sección titulada «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_alertyflow.endpoint_error; noflow.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.*, comoorg.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
Sección titulada «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
Sección titulada «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 aliddel sobre). - Los eventos pueden llegar desordenados, también entre entregas y reenvíos. Dentro de una conversación, ordena por
sequence: solo crece. - Responde
2xxrá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
Sección titulada «Reintentos y fallos»- Éxito = respuesta
2xxen 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
Sección titulada «Lista de fallos y reenvío»- Agotados los intentos, la entrega queda
failedy entra en la lista de fallos del destino, en el panel. - Reenviar crea una entrega nueva del mismo evento (mismo
Messajo-Event-Id, nuevoMessajo-Delivery-Id, intento1). Solo funciona con el destino activo. - Para reenviar varias a la vez, usa Reenviar fallos en el panel o
POST /v1/destinations/{id}/redeliver-failedconsince(yuntil, opcional). Cada llamada pone en cola hasta 1000 fallos y devuelve{ queued, has_more }: conhas_more: true, llama de nuevo. - Las entregas y los eventos se guardan durante 30 días.
Pausa automática
Sección titulada «Pausa automática»- Un destino se pausa solo (
auto_paused) cuando acumula 10 fallos seguidos y lleva fallando al menos 24 horas. Cualquier2xxreinicia la cuenta. - Al pausarse, las entregas todavía en curso de ese destino pasan a
failedcon el errordestination_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
failedcondestination_paused. No se pierde nada: después de corregir el endpoint y reanudar el destino, reenvía los fallos del periodo.
Filtros
Sección titulada «Filtros»Cada destino recibe solo lo que elijas:
- por evento: una lista de patrones. Vale
*(todo),<familia>.*(por ejemplomessage.*oconnection.*) y el tipo exacto (por ejemplomessage.status). Un patrón que no es un tipo conocido ni una familia conocida o reservada se rechaza convalidation_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:
normalizedometa.
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
Sección titulada «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.