Webhook de WhatsApp: la pieza que se rompe en silencio y derriba toda la operación

Qué llega por el webhook

No es solo mensaje. El webhook entrega varios tipos de evento, y cada uno sirve para algo diferente en la operación:

• Mensajes recibidos — texto, audio, imagen, video, documento, ubicación, contacto y respuesta a botón o lista.
• Estado de mensaje enviado — enviado, entregado, leído y fallo, con el motivo del fallo cuando existe.
• Eventos de template — aprobación, rechazo y cambio de estado de un modelo de mensaje.
• Calidad y límite del número — cuando la clasificación de calidad cambia o el nivel de envío sube o baja.
• Eventos de la cuenta — cambios en la cuenta comercial, en el número y en permisos.

Los tres primeros son los que la operación siente todos los días. Los dos últimos son los que evitan sorpresas: la empresa que no escucha evento de calidad solo descubre que el número empeoró cuando el envío se detuvo.

Los campos que deben estar activados

Este es el error silencioso más común de toda la API oficial. La suscripción del webhook tiene campos individuales que deben marcarse uno a uno, y un campo desactivado no genera error en ningún lado: simplemente ese tipo de evento nunca llega.

El resultado típico: la empresa configura el webhook, prueba el envío, funciona, y descubre días después que las respuestas de los clientes nunca aparecieron — porque el campo de mensajes no estaba marcado. O al contrario: los mensajes llegan, pero nadie sabe si fueron leídos, porque el campo de estado quedó fuera.

La verificación que lo resuelve es simple y debe hacerse después de cualquier cambio en la configuración: entrar en la suscripción del webhook, comprobar que los campos de mensaje y de estado están marcados, y enviar un mensaje de prueba desde un celular personal al número de la empresa, verificando si aparece en el sistema en segundos.

La suscripción está en dos lugares diferentes

Otro punto que derriba integraciones: la configuración del webhook no vive en un solo lugar. Existe la configuración a nivel de la aplicación, donde están la URL de callback y el token de verificación, y existe la suscripción por cuenta comercial, que determina de qué cuentas esa aplicación recibe eventos.

Una configuración sin la otra produce exactamente el síntoma más frustrante posible: nada llega y no aparece ningún error. La URL está correcta, el token está correcto, los campos están marcados — y el silencio continúa, porque esa cuenta comercial específica nunca fue suscrita.

Cuando se conecta un número nuevo, o cuando la empresa empieza a usar una cuenta comercial diferente, esa suscripción debe rehacerse. Es la causa número uno de "funcionaba y paró" después de reconectar un número.

Qué debe tener la dirección del webhook

• Ser pública y accesible por internet, con certificado válido. Dirección interna o con certificado vencido es rechazada.
• Responder rápido. Meta espera una confirmación en pocos segundos. Un servidor que procesa todo antes de responder termina recibiendo reenvíos y mensajes duplicados.
• Validar la firma de seguridad enviada en cada solicitud, para garantizar que el evento vino realmente de Meta y no de alguien que descubrió tu URL.
• Soportar ráfagas. Un envío grande genera muchos eventos de estado en poco tiempo.
• Ser estable. Fallas repetidas pueden llevar a Meta a suspender el envío de eventos a esa dirección.

El detalle de la respuesta rápida es lo que más causa duplicación de mensajes en integraciones caseras: lo correcto es confirmar la recepción inmediatamente y procesar después, en segundo plano.

El webhook está atado a la dirección del servidor

Este punto merece destaque porque rompe operaciones enteras de forma silenciosa: si cambias de servidor, de proveedor de hosting o de dirección pública, el webhook apunta a un lugar que ya no existe — y los mensajes simplemente dejan de llegar, sin aviso, sin error visible en el panel.

El envío sigue funcionando normalmente, lo que dificulta el diagnóstico: el equipo puede enviar mensajes, los clientes reciben, y nadie entiende por qué las respuestas desaparecieron. Es una de las fallas que más tardan en identificarse.

La medida es incluir la reconfiguración del webhook en el procedimiento de cualquier cambio de infraestructura, y hacer la prueba de punta a punta justo después — enviar un mensaje desde afuera y confirmar que apareció.

Estado de entrega: qué significa cada uno

Los eventos de estado son los que permiten medir la operación, y cada uno lleva una información diferente:

• Enviado — Meta aceptó el mensaje. No significa que llegó.
• Entregado — llegó al dispositivo del destinatario.
• Leído — el destinatario abrió la conversación, cuando la confirmación de lectura está activa de su lado.
• Fallo — no fue entregado, con un código y una descripción del motivo.

La diferencia entre enviado y entregado es la métrica más reveladora de un envío. Una lista con muchos envíos aceptados y pocas entregas indica base mala, números inexistentes o bloqueo — y insistir en ella es el camino más rápido para derribar la calidad del número.

Webhook y la ventana de 24 horas

Existe una relación directa entre el webhook y la regla comercial más importante de la API oficial: la ventana de atención. Cuando un cliente envía un mensaje, se abre un período en que la empresa puede responder libremente, con mensaje escrito en el momento, sin template y sin costo de iniciar una conversación. Pasado ese período, solo es posible retomar con un modelo aprobado.

El evento que marca el inicio de esta ventana es justamente el que llega por el webhook. Esto significa que una configuración mala no solo causa retraso: puede hacer que la empresa pierda toda la ventana. Si el mensaje del cliente tarda horas en aparecer en el sistema, o no aparece, el vendedor responde tarde o fuera de plazo — y entonces necesita template, con costo y con la frialdad de un mensaje estandarizado.

En la práctica, este es el argumento económico más concreto para tomar en serio el webhook. Cada respuesta perdida por evento que no llegó es, al mismo tiempo, un lead enfriándose y un costo adicional para retomar la conversación. En operaciones con volumen, la diferencia entre un webhook saludable y uno inestable aparece directamente en el costo mensual de conversaciones iniciadas por la empresa.

Los síntomas y qué significa cada uno

• Envío funciona, recepción no — campos de mensaje desactivados o cuenta comercial no suscrita.
• Funcionaba y paró después de reconectar el número — la suscripción de la cuenta comercial debe rehacerse.
• Mensajes llegan duplicados — servidor tarda en confirmar la recepción, lo que provoca reenvío.
• Mensajes desaparecen en horario pico — servidor no soporta la ráfaga de eventos.
• Todo paró después de cambiar de servidor — URL antigua en el webhook.
• Estado nunca se actualiza — campo de estado no suscrito.

Por qué casi nadie debería hacerlo solo

Técnicamente, cualquier empresa puede recibir el webhook en un servidor propio. En la práctica, esto significa mantener un servicio disponible veinticuatro horas al día, manejar ráfagas, validar firma, evitar duplicidad, guardar historial, lidiar con reconexión de número y rehacer configuración cada vez que algo cambia en la infraestructura.

Es trabajo continuo de infraestructura, no un proyecto que termina. Y el costo de errar es alto de una manera específica: el error no aparece como falla, aparece como silencio — cliente que respondió y nadie vio.

Por eso la mayoría de las empresas usa un sistema que ya se encarga de eso y entrega la parte que interesa: la conversación apareciendo en la pantalla del vendedor, el historial guardado, el estado de cada mensaje visible y un informe que muestra entrega, lectura y respuesta sin que nadie tenga que mirar logs.

El webhook no guarda historial — y eso importa

Una confusión común hace que las empresas crean que, por estar en la API oficial, sus conversaciones están guardadas en algún lugar de Meta, listas para ser consultadas después. No es así. La API oficial entrega eventos en tiempo real y no funciona como un archivo de conversaciones: lo que no se almacena por quien recibe simplemente no existe después.

Las consecuencias de esto aparecen en tres momentos muy concretos. Primero, cuando un cliente antiguo vuelve y nadie puede ver lo que se acordó hace seis meses. Segundo, cuando un vendedor sale de la empresa y la conversación debe ser asumida por otra persona. Tercero, cuando surge una discusión sobre lo que se prometió o no, y la empresa no tiene registro.

Por eso la pregunta sobre dónde queda el historial debería venir antes que la pregunta sobre precio al elegir cualquier proveedor. Un sistema que guarda todas las conversaciones, permite búsqueda por cliente y exporta los datos cuando lo pidas transforma el webhook en memoria de la empresa. Sin eso, cada mensaje recibido es un evento que pasa — visto por una persona, en un momento, y luego perdido.

Cómo probar si todo está funcionando

Un guion de cinco minutos que debería repetirse después de cualquier cambio:

• envía un mensaje desde un celular personal al número de la empresa y confirma que aparece en el sistema en segundos;
• responde por el sistema y confirma que el estado cambia de enviado a entregado y luego a leído;
• envía una imagen y un audio, porque tipos de medios a veces fallan por separado;
• prueba un botón o una lista interactiva, si usas ese recurso;
• verifica si un template enviado registra el estado correctamente.

Hacer esta prueba siempre que un número sea conectado, reconectado o migrado evita descubrir tarde que la operación pasó días sin recibir nada.

Por dónde empezar

Si ya operas: haz la prueba de punta a punta hoy, verifica si los campos de mensaje y estado están suscritos, comprueba si la cuenta comercial está en la lista de suscripciones de la aplicación y registra en algún lugar que cambiar de servidor exige reconfigurar el webhook. Si estás empezando ahora: elige un sistema que asuma esta capa, y usa el tiempo que sobra para cuidar lo que realmente genera ingresos — velocidad de respuesta, distribución de leads y seguimiento. Webhook bien configurado es invisible; mal configurado, es silencio — y silencio, en este canal, es venta perdida sin que nadie lo note.