Webhooks — Changelog
Historial de cambios del payload de los webhooks y política de aviso previo.
Esta página registra todo cambio en el payload de los webhooks salientes. Si tiene una
integración activa, es la página para vigilar.
Octubre de 2026 — Instagram y Messenger
Cambio aditivo dentro de la v1: ningún campo existente cambia.
🟢 Eventos nuevos
Cuatro eventos para las conversaciones de Instagram y Facebook Messenger, filtrados por canal
social: social_message_received, social_message_sent, social_message_status y
social_conversation_updated. Detalle en
Eventos de Instagram y Messenger.
🟢 Campos nuevos
channel_type y channel_uuid en la familia encuesta. Las encuestas de Instagram y
Messenger llegan a todos sus webhooks de encuestas, igual que antes. Ahora traen el canal
para que pueda distinguirlas: channel_type es whatsapp, messenger o instagram, y
channel_uuid es null en WhatsApp.
21 de agosto de 2026 — Respuestas de WhatsApp Flows
Cambio aditivo dentro de la v1: ningún campo existente cambia.
🟢 Campos nuevos
flow_id y bsuids en wa_flow_response_received. Los dos viajan siempre en ese evento;
wa_flow_sent no los trae.
flow_ides el id del Flow en Meta que el contacto respondió, onullsi no se pudo
resolver.bsuidslista los identificadores del contacto, uno por portafolio de negocio de Meta, con
la línea donde se observó cada uno. Sirve para saber por cuál de sus números le escribió la
persona.
Detalle y ejemplo en Eventos de mensaje.
v1 — agosto de 2026
Primera versión del contrato documentado. Desde ahora la forma del payload está declarada
campo por campo y cubierta por pruebas automáticas que fallan si cambia.
🟢 Campos nuevos
bsuid y wa_username en las familias mensaje, encuesta y publicidad.
Meta empezó a desplegar la opción de ocultar el número de teléfono. Un contacto que la
activa llega sin teléfono, y su clave de conversación (wa_id, contact_wa_id) pasa a ser
un BSUID en vez de un número. Estos dos campos permiten distinguir el caso:
| Familia | Campos agregados |
|---|---|
Mensaje (receive_message, send_message, send_bot_message, status_message, wa_flow_*) | bsuid, wa_username |
Encuesta (los cinco survey_*) | bsuid, wa_username |
Publicidad (message_facebook_advertising) | bsuid, wa_username |
Detalle completo y ejemplos en Identidad del contacto.
🟡 Campos que ahora están siempre
Antes, algunos campos podían aparecer o no según qué acción hubiera disparado el evento.
Ahora el conjunto documentado viaja completo, con null cuando no hay valor:
| Antes | Ahora |
|---|---|
create_contact traía menos campos que update_contact para el mismo contacto | Los dos mandan el conjunto completo |
labels y custom_fields podían venir o no | Van siempre en los cuatro eventos de contacto; [] si no hay |
blocked y possible_invalid podían llegar como null en unos eventos y booleanos en otros | Siempre booleanos (salvo blocked en delete_contact, que es null) |
bsuid y wa_username solo aparecían cuando había valor | Van siempre, con null si no hay |
Este es el cambio que puede afectarle. Si su integración inserta el payload completoen una tabla —en vez de tomar los campos que necesita— un campo nuevo hace fallar el
INSERT. Ver cómo tolerar campos nuevos.
🟡 Cambio de comportamiento en delete_contact
delete_contactdelete_contact ahora se dispara también cuando el borrado se hace desde la plataforma,
no solo desde DELETE /v1/contacts/{id} de la API.
Si tiene delete_contact activo, va a empezar a recibir eventos que antes no recibía —
incluidos los borrados masivos, que disparan un evento por contacto.
🟢 Campo version
versionTodos los payloads incluyen ahora data.version, hoy siempre 1. Existe desde ya para que
el día que haya una v2 su integración pueda ramificar sin que haya que agregar el campo justo
en el momento delicado.
🔴 Nada se quitó ni se renombró
Ningún campo que existía antes desapareció ni cambió de significado.
Mayo de 2026 — bsuid y wa_username en los eventos de contacto
bsuid y wa_username en los eventos de contactoLos dos campos empezaron a aparecer en create_contact, update_contact, delete_contact y
status_bot_contact sin anuncio previo.
Desde la v1 eso no puede repetirse: los campos del payload se declaran de forma explícita, uno
por uno, así que ningún cambio interno publica un campo por su cuenta — y todo campo nuevo
queda registrado en esta página.
Política de aviso
Dentro de la v1:
| Tipo de cambio | ¿Hay aviso? |
|---|---|
| Se agrega un campo | Se publica acá, en este changelog |
| Se quita o se renombra un campo | No ocurre en v1 |
| Cambia el significado de un campo | No ocurre en v1 |
Para una v2 —el día que haya que romper algo— el compromiso es: aviso previo a las
cuentas con integración activa, las dos versiones conviviendo durante la transición, y
retiro de la v1 solo después.
Su integración debe tolerar campos que no conoce. Es la única condición para que uncambio aditivo no la rompa, y la razón por la que podemos agregar campos sin coordinar con
cada cuenta. Tome los campos que necesita en vez de insertar el payload completo a ciegas.
Cuando el cambio viene de Meta
Algunos cambios no los originamos nosotros: Meta modifica su plataforma —tipos de mensaje
nuevos, la opción de ocultar el número— y esos cambios llegan a los webhooks. Las fechas de
Meta se mueven y no siempre se anuncian con antelación a los proveedores.
Cuando pase, lo vamos a registrar acá igual, con la fecha real en que empezó a llegarle.
Campos en revisión
Un campo marcado acá sigue funcionando exactamente igual y no se va a quitar en v1. Se
lista para que no construya lógica nueva sobre él.
| Campo | Dónde | Por qué |
|---|---|---|
possible_invalid | Familia contacto | Bandera heurística interna sobre si el teléfono parece inválido. No refleja ninguna verificación contra Meta. Candidata a salir en v2 |
data | Familia mensaje | Campo interno cuyo formato no forma parte del contrato. Viene vacío en la mayoría de los mensajes. Para adjuntos use filename y caption |
Updated 10 days ago