Cómo usar webhooks de WhatsApp para crear automatizaciones en tiempo real con Z-API

Existe un recurso técnico que hace que cualquier automatización sea más inteligente y eficiente: los webhooks de WhatsApp.

En la práctica, los webhooks son los que permiten que tu sistema sepa, en tiempo real, que ha llegado un nuevo mensaje. Sin ellos, tu integración queda prácticamente a ciegas: no sabe cuándo escribió el cliente, no puede responder automáticamente y tampoco puede activar flujos que dependen de la interacción del usuario.

Un webhook es un mecanismo utilizado en internet para que una aplicación se comunique con otra y envíe datos en tiempo real cada vez que ocurre un evento determinado.

De esta manera, ambos sistemas pueden intercambiar información sin necesidad de que exista una acción externa.

Cada vez que el número conectado recibe o genera una interacción, Z-API realiza una solicitud POST a una URL configurada previamente, con un cuerpo JSON específico para cada tipo de evento.

En este artículo, veremos con más detalle cómo funcionan los webhooks de Z-API, cuáles están disponibles, cómo configurar cada uno y cómo utilizarlos para construir automatizaciones confiables en tiempo real.

¿Qué son los webhooks de WhatsApp y qué función cumplen en las automatizaciones?

Antes de entrar en los detalles técnicos, conviene reforzar el concepto principal: un webhook es una URL de tu servidor que Z-API llama automáticamente cada vez que ocurre un evento en la instancia.

Cuando se recibe un mensaje, cuando un mensaje enviado es entregado, cuando la instancia se desconecta o cuando cambia el estado de un chat, Z-API envía un payload HTTP POST a la URL que configuraste con todos los detalles del evento.

La diferencia entre polling y webhook es fundamental para entender por qué los webhooks son el modelo adecuado para automatizaciones de WhatsApp:

• Polling: ocurre cuando tu sistema consulta periódicamente la API preguntando: “¿hay algún mensaje nuevo?”. Cada 5, 10 o 30 segundos se realiza una solicitud. La mayoría no devuelve novedades y, cuando finalmente llega un mensaje, el sistema solo lo detecta en la siguiente consulta. Esto genera retrasos en la respuesta, consumo innecesario de recursos y problemas de escalabilidad en operaciones con muchas instancias.
• Webhook: invierte esta lógica. Tu sistema no necesita preguntar. Z-API lo notifica en el momento exacto en que ocurre el evento, sin necesidad de consultas repetitivas y sin depender de cuántas instancias estén activas.

Para automatizaciones que necesitan responder en tiempo real, como atención al cliente, calificación de leads y notificaciones bidireccionales, esta diferencia puede determinar si una integración funciona de manera fluida o genera frustración.

Un punto importante de la documentación oficial: no es necesario configurar todos los webhooks. Sin embargo, cuanto mayor sea el control sobre tu instancia, más recursos podrás aprovechar y más valor podrás construir con Z-API. Configura los que tengan sentido para tu caso de uso y amplía la estructura a medida que evoluciona la operación.

Los webhooks disponibles en Z-API

La documentación de Z-API organiza los webhooks de WhatsApp en cuatro tipos principales, cada uno con una función específica:

Delivery (Al enviar)

El webhook de delivery informa que tu mensaje fue entregado a WhatsApp. Importante: esto no significa necesariamente que el contacto lo haya recibido. Para obtener información sobre recepción y lectura, es necesario monitorear el webhook de status.

El endpoint para configurar este webhook es:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-delivery

El payload de retorno incluye los siguientes campos:

• phone: número de teléfono de destino del mensaje
• zaapId: identificador del mensaje dentro de la conversación
• messageId: identificador del mensaje en WhatsApp
• instanceId: identificador de la instancia
• momment: timestamp en milisegundos del momento en que se generó el evento
• type: tipo del evento, en este caso DeliveryCallback
• error: aparece solo en casos de error y contiene la descripción del problema ocurrido durante el envío

Ejemplo de retorno exitoso:

{
  "phone": "554499999999",
  "zaapId": "A20DA9C0183A2D35A260F53F5D2B9244",
  "messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
  "instanceId": "instance.id",
  "momment": 1777494009341,
  "type": "DeliveryCallback"
}

Este webhook es especialmente útil para sistemas que necesitan confirmar que el mensaje llegó a WhatsApp antes de activar el siguiente paso del flujo, como actualizar un estado en el CRM o iniciar una etapa posterior de la automatización.

Para ver todos los ejemplos de retorno según cada situación, incluidos escenarios de error, consulta la página de ejemplos de retorno de Al enviar en la documentación oficial.

Receive (Al recibir)

Este es el webhook más utilizado en automatizaciones. Se ejecuta cada vez que alguien interactúa con el número de WhatsApp conectado, es decir, cada vez que llega un mensaje.

El endpoint para configurarlo es:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-received

Un detalle importante de la documentación: este webhook también puede ejecutarse cuando la instancia está configurada para notificar mensajes enviados por el propio número conectado. Veremos esto más adelante en la sección sobre update-notify-sent-by-me.

Otro punto relevante para quienes trabajan con archivos multimedia: los archivos como imágenes, documentos y audios permanecen disponibles durante 30 días en el almacenamiento de Z-API.

Después de ese período, los archivos se eliminan. Esto debe tenerse en cuenta en arquitecturas que dependen del procesamiento posterior de contenido multimedia.

El webhook de recepción admite todos los tipos de mensajes de WhatsApp.

Para consultar ejemplos de payload según el tipo de mensaje, incluidos texto, imagen, audio, documento, ubicación, contacto, encuesta y botones, consulta la página de ejemplos de retorno de Al recibir en la documentación oficial.

Status

El webhook de status notifica todos los cambios de estado que atraviesa un mensaje: si fue recibido, leído, respondido o eliminado.

Un punto importante de la documentación: un mismo mensaje puede pasar por varios estados e incluso recibir el mismo estado más de una vez, como puede ocurrir con “respondido”.

Esto significa que tu sistema debe estar preparado para recibir múltiples eventos de status para un mismo mensaje y tratarlos de acuerdo con la lógica de negocio correcta.

Este webhook es fundamental para sistemas que necesitan saber si el cliente leyó un mensaje antes de activar el siguiente paso, por ejemplo, enviar un follow-up automático solo a quienes no lo han leído o actualizar el CRM cuando el mensaje se confirme como leído.

Disconnected (Al desconectar)

Este webhook se ejecuta cada vez que Z-API detecta algún tipo de indisponibilidad en la comunicación, ya sea entre el teléfono y WhatsApp o entre el teléfono y Z-API.

En operaciones de producción, monitorear los eventos de desconexión es fundamental, porque una instancia desconectada sin ser detectada puede hacer que lleguen mensajes que no se procesan y que la operación se detenga sin que nadie lo note.

Con el webhook de desconexión configurado, tu sistema recibe la alerta inmediatamente y puede activar automáticamente un proceso de reconexión.

¿Cómo configurar los webhooks en Z-API?

La documentación de Z-API ofrece dos formas de configurar los webhooks:

Desde el panel

Accede al panel de administración. En Instancias, haz clic en el icono de visualización de la instancia correspondiente y, en el menú de tres puntos, selecciona “editar”. El campo de webhook aparecerá en la pantalla de edición de la instancia.

Mediante la API

Cada webhook tiene su propio endpoint de configuración mediante PUT. Debes enviar la URL de tu sistema en el campo value del body de la solicitud.

Un punto crítico de la documentación: Z-API no acepta webhooks que no utilicen HTTPS. Antes de configurar cualquier webhook, asegúrate de que la URL de tu endpoint cuente con un certificado SSL válido.

Durante el desarrollo local, herramientas como ngrok pueden utilizarse para crear un túnel HTTPS temporal para realizar pruebas.

Actualizar todos los webhooks de una sola vez

Para quienes quieren apuntar todos los webhooks a la misma URL de una forma más sencilla, Z-API ofrece un endpoint específico:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-all-webhooks

El body acepta dos campos:

{
  "value": "https://direccion-de-tu-sistema.com/instancia/TU_INSTANCIA/webhook",
  "notifySentByMe": true
}

El campo value define la URL de todos los webhooks. El campo opcional notifySentByMe habilita las notificaciones de webhook para mensajes recibidos y enviados por el propio número conectado, algo que veremos con más detalle en la siguiente sección.

Este endpoint es especialmente útil durante la configuración inicial o cuando necesitas migrar todos los webhooks a una nueva URL sin tener que llamar a cada endpoint individualmente.

La función notifySentByMe: qué es y cuándo utilizarla

Esta configuración merece especial atención porque modifica el comportamiento predeterminado del webhook de recepción.

Por defecto, el webhook Al recibir solo notifica los mensajes que otras personas envían a tu número. Cuando se habilita notifySentByMe, también empieza a notificar los mensajes enviados por el propio número conectado.

El endpoint para configurar esta función de forma individual es:

PUT https://api.z-api.io/instances/{id}/token/{token}/update-notify-sent-by-me

Con el siguiente body:

{
  "notifySentByMe": true
}

Una advertencia importante de la documentación: para que esta función opere correctamente, debe existir un webhook configurado para el evento Al recibir. De lo contrario, no habrá un endpoint al que entregar esas notificaciones.

¿Cuándo tiene sentido utilizar esta función?

En sistemas de atención multiagente, donde distintos agentes envían mensajes desde el mismo número, habilitar notifySentByMe permite que el sistema registre todos los mensajes enviados, independientemente de quién los haya enviado.

Esto garantiza que el historial de conversaciones en el CRM esté completo, incluyendo los mensajes enviados por la empresa al cliente.

En arquitecturas de auditoría, donde es necesario registrar toda la comunicación que pasa por el número, esta funcionalidad ayuda a garantizar que ningún mensaje quede fuera del log.

En sistemas de sincronización entre múltiples dispositivos, notifySentByMe permite que el sistema sepa qué se envió en cada sesión y mantenga un estado consistente.

Consulta también: Cómo integrar una API de WhatsApp con tu CRM.

Cómo configurar el webhook de recepción: paso a paso

Este es el flujo completo para poner en funcionamiento el webhook de recepción en producción:

1. Crear el endpoint en tu sistema

Tu servidor debe exponer una URL HTTPS que acepte solicitudes POST. Este endpoint recibe los payloads de Z-API y debe devolver un status 200 para confirmar la recepción.

2. Configurar la URL en Z-API

Realiza una solicitud PUT al endpoint de configuración con la URL de tu sistema:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-received

Body:

{
  "value": "https://direccion-de-tu-sistema.com/instancia/TU_INSTANCIA/receive"
}

3. Procesar el payload recibido

Cuando llega un mensaje al número conectado, Z-API realiza una solicitud POST a la URL configurada con el payload del mensaje. Tu sistema extrae los campos relevantes, procesa el mensaje y ejecuta la lógica de negocio correspondiente.

4. Habilitar notifySentByMe si es necesario

Si tu caso de uso también necesita recibir notificaciones de los mensajes enviados por el propio número, configura:

PUT https://api.z-api.io/instances/{id}/token/{token}/update-notify-sent-by-me

Body:

{
  "notifySentByMe": true
}

Casos de uso donde los webhooks marcan la diferencia

Con los webhooks de WhatsApp configurados correctamente, estos son algunos de los casos de uso que se vuelven posibles en producción:

Atención en tiempo real con un agente de IA

El webhook de recepción es el disparador de cualquier automatización inteligente en WhatsApp. Cuando llega el mensaje, el payload se envía al sistema, el LLM procesa el contenido y la respuesta vuelve a enviarse mediante Z-API.

Sin un webhook de recepción confiable, el agente no puede operar en tiempo real.

Confirmación de entrega y lectura en el CRM

El webhook de delivery confirma que el mensaje llegó a WhatsApp. El webhook de status confirma cuándo fue recibido y leído por el destinatario.

Al procesar ambos eventos, el CRM puede actualizar automáticamente el estado real de cada comunicación sin intervención manual.

Detección y recuperación automática de desconexiones

El webhook de desconexión permite que el sistema detecte inmediatamente cuando una instancia pierde la conexión y active de forma automática el proceso de reconexión, minimizando el tiempo de inactividad de la operación.

Historial completo de conversaciones

Con notifySentByMe habilitado, el sistema registra tanto los mensajes recibidos como los enviados, construyendo un historial completo de cada conversación que cualquier agente puede consultar desde el CRM.

Automatizaciones bidireccionales

Se envía una notificación al cliente mediante Z-API. Cuando el cliente responde, el webhook de recepción entrega esa respuesta al sistema. El sistema la procesa y activa automáticamente la siguiente etapa del flujo.

Todo el ciclo ocurre sin intervención humana.

Buenas prácticas para garantizar confiabilidad en producción

Configurar los webhooks es solo el primer paso. Garantizar que funcionen de forma confiable en producción requiere algunas prácticas adicionales:

Responder 200 rápidamente

El endpoint debe devolver status 200 inmediatamente después de recibir el payload.

Si el procesamiento tarda más tiempo, envía el evento a una cola asíncrona y devuelve el 200 antes de procesarlo.

Si el endpoint tarda demasiado en responder, Z-API puede interpretar la solicitud como un fallo.

Gestionar duplicados con idempotencia

En situaciones de inestabilidad de red, Z-API puede volver a enviar el mismo evento.

Utiliza el identificador único del mensaje presente en el payload para comprobar si el evento ya fue procesado antes de ejecutar cualquier acción.

Procesar el mismo mensaje dos veces puede generar respuestas duplicadas para el cliente.

Utilizar siempre HTTPS

La documentación es clara: Z-API no acepta webhooks que no utilicen HTTPS.

Asegúrate de que tu endpoint tenga un certificado SSL válido antes de configurar cualquier webhook.

Monitorear la salud de los endpoints

Configurar alertas para detectar cuándo los webhooks dejan de recibir eventos es fundamental para identificar fallos de configuración o problemas de infraestructura antes de que afecten la operación.

No compartir ID ni token

La documentación de Z-API refuerza este punto: nunca compartas el ID ni el token de la instancia con terceros.

Estas credenciales proporcionan acceso completo a la instancia y deben tratarse como información sensible.

Recursos de documentación para profundizar

Para quienes quieren ir más allá de lo básico, la documentación oficial de Z-API incluye recursos adicionales para escenarios más avanzados.

La página de ejemplos de retorno de Al enviar detalla los distintos escenarios posibles del webhook de delivery, incluidos los tipos de error que pueden aparecer en el campo error del payload.

La página de ejemplos de retorno de Al recibir incluye ejemplos de payload para todos los tipos de mensajes compatibles, como texto, imagen, audio, video, documento, ubicación, contacto, encuesta, botones y más.

La introducción a los webhooks ofrece una visión general completa de todos los tipos disponibles y las instrucciones de configuración tanto desde el panel como mediante la API.

El endpoint para actualizar todos los webhooks resulta especialmente útil durante la configuración inicial o en migraciones, cuando es necesario dirigir todos los webhooks a una nueva URL al mismo tiempo.

Configura tus webhooks en Z-API y construye tus automatizaciones

Los webhooks de WhatsApp son la base técnica de cualquier automatización que necesita operar en tiempo real.

Z-API ofrece un conjunto completo de webhooks que cubre los principales eventos de una operación: recepción de mensajes, confirmación de entrega, cambios de estado, desconexiones de la instancia y mensajes enviados por el propio número conectado.

Configurar correctamente, utilizar HTTPS, responder 200 rápidamente, gestionar duplicados y monitorear la salud de los endpoints son prácticas que convierten un webhook funcional en una infraestructura confiable a largo plazo.

Para quienes están construyendo automatizaciones con Z-API, la documentación oficial contiene todo lo necesario para implementar cada webhook con precisión, desde los endpoints de configuración hasta ejemplos completos de payload para cada tipo de evento.

Consulta la documentación de webhooks de Z-API y pruébalos en la práctica. 👉 Crea tu cuenta gratis