14 de noviembre, 2026 · Fabrizzio Zelada · 11 min de lectura

Webhooks de WhatsApp Business API: guía técnica para pymes en 2026

Respuesta corta: un webhook de WhatsApp Business API es un endpoint HTTPS público que Meta llama cada vez que ocurre un evento en tu número (mensaje entrante, cambio de estado, plantilla aprobada). Configurarlo bien requiere un handshake con token, verificar la firma HMAC-SHA256 de cada petición, responder en menos de 20 segundos con HTTP 200 y almacenar el evento antes de procesarlo. En esta guía de noviembre de 2026 explicamos el handshake, los payloads reales, la arquitectura mínima para producción y los errores que tiran la integración en la primera semana.

Lee también: antes de tocar webhooks conviene tener claro el modelo de acceso: lee nuestra guía de WhatsApp Business API para pymes y la comparativa de proveedores en España.

¿Qué es un webhook de WhatsApp Business API y por qué lo necesitas?

Un webhook es la vía por la que Meta te notifica en tiempo real los eventos que ocurren en tu número de WhatsApp Business. En vez de que tu backend pregunte cada pocos segundos si hay mensajes nuevos (polling, prohibido en la Cloud API), Meta hace una petición HTTPS POST a la URL que configuras cuando el evento se produce.

Sin webhook, no hay integración posible con un CRM conectado a WhatsApp, un agente de IA personalizado, ni un sistema de atribución por canal. El webhook es la columna vertebral de todo lo que viene después: el agente responde porque recibió un evento messages; el dashboard marca el mensaje como leído porque llegó un statuses con valor read; la campaña de carrito abandonado se detiene porque entró un message_template_status_update.

Según la documentación oficial de Meta for Developers (actualizada el 26 de junio de 2026), los permisos obligatorios son whatsapp_business_messaging para eventos de mensajes y llamadas, y whatsapp_business_management para el resto. Sin esos permisos tu webhook no recibe nada, aunque la URL esté bien configurada.

En Zenia Partners configuramos webhooks de WhatsApp Business API para pymes españolas y latinoamericanas. En la mayoría de casos no construimos el endpoint desde cero: lo integramos sobre la infraestructura del cliente (su CRM, su agente de IA personalizado) o sobre nuestra plataforma. En los dos escenarios los retos técnicos son los mismos y son los que vamos a desgranar.

¿Cómo funciona el handshake de verificación de webhook?

Antes de que Meta empiece a mandarte eventos, exige un handshake de validación. Si no lo pasas, la URL no se registra y no verás un solo POST. El handshake es un simple GET que Meta envía con tres parámetros en la query string.

Paso 1: Meta envía un GET al endpoint

Cuando guardas la URL en el panel de App de Meta, el servidor envía una petición GET https://tu-endpoint/webhook?hub.mode=subscribe&hub.verify_token=TU_TOKEN&hub.challenge=1234567890. El valor de hub.verify_token es el que tú definiste en el panel; hub.challenge es un número aleatorio que Meta genera para la prueba.

Paso 2: Tu endpoint responde con el challenge en texto plano

Tu backend debe comparar el hub.verify_token recibido con el que guardaste en una variable de entorno. Si coinciden, devuelves el valor de hub.challenge con un Content-Type: text/plain y HTTP 200. Si no coinciden, devuelves 403. En ningún caso devuelvas 500: Meta interpretará que el endpoint está caído y bloqueará futuros intentos durante 30 minutos.

Paso 3: Meta registra la URL y empieza a enviar POSTs

A partir de ese momento cada evento llega como POST con un cuerpo JSON (payload) y una cabecera X-Hub-Signature-256. Esa cabecera es la firma HMAC-SHA256 del cuerpo usando como clave el App Secret de tu aplicación de Meta, no el verify_token. Confundirlos es el error más común de la primera semana.

Paso 4: Validación de firma en producción

En producción tu endpoint debe calcular hmac_sha256(app_secret, raw_body) y compararlo (en tiempo constante, para evitar timing attacks) con el valor de X-Hub-Signature-256 tras quitar el prefijo sha256=. Si no valida, devuelve 403 y descarta el evento. Esta validación es lo único que separa tu webhook de ser un endpoint abierto para cualquiera que descubra la URL.

Un detalle clave: la firma se calcula sobre el cuerpo crudo, antes de cualquier parseo a objeto. Si tu framework (Express, FastAPI, Rails) te da el body ya parseado, la firma no cuadrará nunca. Hay que capturar el raw body explícitamente.

Eventos y payloads principales que vas a recibir

Meta agrupa todos los webhooks de WhatsApp Business bajo un mismo objeto: whatsapp_business_account. Dentro del array entry.changes llega un campo field que te dice qué tipo de evento es. Estos son los cinco que vas a manejar el 95% del tiempo.

Desliza para ver la tabla completa →

Campo fieldCuándo se disparaDato clave del payloadQué hacer en el backend
messages (type=text, image, interactive, etc.)Un usuario envía un mensaje a tu númeromessages[0].from, id, timestamp, text.bodyEncolar al agente de IA y responder <20 s
statusesCambia el estado de un mensaje saliente (sent, delivered, read, failed)statuses[0].status, recipient_id, conversation.origin.typeActualizar el estado en el CRM, calcular SLA
message_template_status_updateMeta aprueba o rechaza una plantillaevent (APPROVED, REJECTED), reasonReactivar o bloquear campañas que usen esa plantilla
phone_number_quality_updateCambia la calidad del número (GREEN, YELLOW, RED)current_quality, eventAlertar al equipo si baja a YELLOW o RED
account_updateMeta impone un ban, límite o cambio de tierevent, ban_info, restriction_infoParada automática de envíos salientes

El payload máximo que Meta envía es de 3 MB por petición (según el reference de status messages de Meta). En la práctica el 99% de los eventos pesa menos de 10 KB, pero el límite existe porque un messages de tipo imagen con metadatos de contexto puede crecer rápido. Tu endpoint debe aceptar al menos 5 MB de body para evitar truncamientos en picos.

Un error silencioso frecuente: Meta agrupa varios eventos en un mismo POST. El array entry[0].changes[0].value.messages puede contener 1, 5 o 20 mensajes. Si tu código procesa solo el primero, pierdes el resto sin ver ningún error en los logs.

Seguridad y buenas prácticas en producción

Un webhook mal protegido es un vector de ataque directo a tu CRM. Estas son las cinco prácticas que aplicamos en toda implementación de Zenia Partners, y que encontramos ausentes en el 80% de endpoints que auditamos al tomar un cliente nuevo.

1. Validar X-Hub-Signature-256 en cada petición

No basta con validarla una vez en pruebas. Cada POST debe pasar la verificación HMAC-SHA256. Si la firma no coincide, devuelve 403 y tira el evento al syslog con nivel warning. En Node.js: crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)).

2. Responder HTTP 200 en menos de 20 segundos

Meta retira el evento si tardas más de 20 segundos. Y si recibe 5xx o timeouts seguidos durante 7 días, desactiva el webhook. La regla es simple: tu endpoint valida firma, guarda el evento crudo en una cola (Redis, SQS, RabbitMQ) y devuelve 200. El procesamiento (llamada al modelo de IA, escritura en CRM, respuesta por WhatsApp) va en un worker aparte.

3. Idempotencia por messages[i].id

Meta reenvía el mismo evento si no recibió el 200 a tiempo. El id del mensaje es único. Guarda cada id procesado con un TTL de 7 días y descarta duplicados. Sin esto, un pico de latencia se convierte en respuestas duplicadas al cliente y en un agente que se dispara dos veces.

4. Allowlist de IPs no funciona

Meta no publica rangos de IP estables para webhooks de Cloud API. Si pones un firewall por IP vas a bloquear eventos legítimos en cuanto roten los servidores. La firma HMAC es lo que te autentica, no la IP.

5. Dead letter queue y observabilidad

Todo evento que falle procesado tras 3 reintentos va a una DLQ para revisión humana. Métricas mínimas a monitorizar: tasa de eventos recibidos por minuto, latencia P50/P95/P99 del endpoint, tasa de 403 por firma inválida, mensajes en la DLQ. Sin esto, cuando el agente de IA deje de responder un sábado por la noche nadie se va a enterar hasta el lunes.

¿Cuánto cuesta construir y operar un webhook de WhatsApp Business API?

El coste real tiene tres capas: la Cloud API de Meta, la infraestructura donde corre el endpoint y el tiempo de ingeniería. Noviembre de 2026:

Desliza para ver la tabla completa →

OpciónCoste mensualTiempo de setupQué incluyePara quién
Cloud API directa de Meta + endpoint propioCoste por conversación de 24 h (según país) + 15-40 € de infra2-4 semanas de ingenieríaEndpoint, cola, worker, validación firma, CRMEquipo con dev backend fijo que quiere control total
BSP (360dialog, Twilio, Infobip, MessageBird)Fee mensual del BSP (15-80 €) + coste por conversación de Meta3-7 díasWebhook del BSP, panel, plantillas, soportePymes sin backend o con equipo pequeño
Plataforma vertical (Zenia Partners)Starter 997 € de setup + 297 €/mes, Growth 497 €/mes, Enterprise a medida2-5 semanasBSP, webhook, agente de IA personalizado, CRM a medida, integracionesPyme que quiere el resultado funcionando, no el proyecto
Construir de cero sin proveedor0 € si ya tienes infra, pero 40-120 h de ingeniería4-8 semanasLo que decidasEquipos técnicos con tiempo y sin urgencia

Zenia Partners es una agencia con sede en Madrid que trabaja con pymes en España y Latinoamérica. Construimos un agente de IA personalizado sobre WhatsApp y web que responde en menos de un minuto, cualifica leads y agenda citas 24/7, todo conectado al CRM con atribución por canal. Si tu caso encaja en la última columna de la tabla (quieres el resultado, no el proyecto), la implementación arranca con setup 997 € + 297 €/mes (plan Starter, octubre de 2026).

Si en cambio tu equipo tiene dev backend y solo necesita orientación técnica, publicamos esta guía precisamente porque creemos que entender la capa de abajo te hace mejor cliente de cualquier proveedor (incluidos nosotros).

Arquitectura de referencia para un webhook en producción

Esta es la arquitectura que desplegamos por defecto. Se puede simplificar para proyectos pequeños, pero cada componente resuelve un problema real que aparece en cuanto el tráfico pasa de 500 eventos al día.

Componente 1: Edge handler (función serverless o contenedor ligero)

Vercel, Cloudflare Workers, AWS Lambda o un Fastify en Fly.io. Su única responsabilidad: validar firma, encolar el raw body y devolver 200. Nada de modelos de IA ni queries al CRM aquí. Latencia objetivo P95 inferior a 300 ms.

Componente 2: Cola persistente

Redis Streams, AWS SQS, Google Pub/Sub o RabbitMQ. El evento vive aquí hasta que un worker lo procesa. Esto desacopla el ritmo de Meta (que te envía picos) del ritmo del backend (que puede saturarse).

Componente 3: Worker con reintentos exponenciales

Lee de la cola, deduplica por messages[i].id, enriquece con contexto del CRM, llama al modelo de IA y envía la respuesta por la Graph API de WhatsApp. Reintentos con backoff: 1s, 5s, 30s, 2m. Tras 3 fallos, al DLQ.

Componente 4: CRM con write-ahead log

Cada evento se registra en una tabla de eventos antes de modificar el estado del contacto. Si algo falla, puedes reproducir la conversación entera a partir del log. No es opcional: en el momento en que un cliente te acuse de no haber recibido un mensaje, este log es tu prueba.

Componente 5: Observabilidad

Prometheus + Grafana, Datadog o la combinación que tu equipo use. Los cuatro gráficos imprescindibles: tasa de eventos recibidos, latencia del edge handler, longitud de la cola y errores del worker. Alertas en PagerDuty o Opsgenie para cola inflada y worker caído.

Preguntas frecuentes

¿Cuál es la diferencia entre el verify_token y el App Secret?

El verify_token es una cadena que tú defines y se usa solo durante el handshake inicial (el GET que Meta envía al registrar la URL). El App Secret es una clave que Meta te asigna en tu aplicación y es la que se usa como clave HMAC para firmar cada POST de eventos. Confundirlos es el error más común y provoca que todas las firmas devuelvan 403.

¿Por qué mi webhook recibe el handshake pero no los eventos?

La causa casi siempre es que tu aplicación de Meta no está suscrita a los campos concretos (messages, statuses, etc.) en el panel de WhatsApp Business Account. El handshake valida la URL, pero las suscripciones a campos son un paso separado que hay que activar manualmente para cada WABA.

¿Puedo usar un único webhook para varios números de WhatsApp Business?

Sí. Si todos los números cuelgan de la misma WhatsApp Business Account, un solo endpoint recibe todos los eventos y los diferencias por el campo entry[0].changes[0].value.metadata.phone_number_id. Si están en WABAs distintas, necesitas una URL por WABA o un routing interno a partir de la cabecera X-Hub-Signature-256 con App Secrets distintos.

¿Qué pasa si mi endpoint cae durante unas horas?

Meta reintenta durante un periodo (minutos a horas, depende del tipo de evento) y luego descarta los eventos no entregados. Si la caída supera los 7 días, Meta desactiva el webhook y hay que reactivarlo manualmente. Por eso la cola persistente es crítica: te permite estar fuera durante minutos sin perder nada.

¿Se puede desarrollar webhooks sin un dominio público?

Para pruebas, sí: con ngrok o Cloudflare Tunnel expones tu localhost. Para producción no vale: el certificado TLS debe ser válido y la URL estable. Meta no acepta IPs ni dominios self-signed.

¿El webhook está disponible en la WhatsApp Business App (no API)?

No. La WhatsApp Business App gratuita no expone webhooks ni API. Para webhooks necesitas WhatsApp Business Platform (Cloud API o On-Premises API), que es un producto distinto con su propia facturación por conversación.

¿Quieres el webhook y el agente de IA en producción sin dolor?

En Zenia Partners montamos la infraestructura completa: proveedor de WhatsApp Business API, webhook validado, agente de IA personalizado y CRM a medida. Cuéntanos tu caso y te respondemos en menos de 24 h.

Todo esto parte de lo mismo: automatizar WhatsApp con IA para que ningún mensaje se quede sin responder.

Hablar por WhatsApp ahora Agendar llamada gratuita

¿Buscas una integración completa?

Zenia Partners cubre desde el BSP hasta el CRM y el agente de IA. Entra en la guía que mejor te encaje:

Automatización WhatsApp con IA → Cloud API vs Business App → Integrar CRM con WhatsApp → Zenia Partners (home) →
Ver cobertura completa