Resumen
Los webhooks son un método para que las aplicaciones envíen datos en tiempo real a otros sistemas cuando ocurren eventos específicos. A diferencia de las APIs tradicionales que requieren consultas constantes, los webhooks envían actualizaciones automáticamente, lo que los hace eficientes para notificaciones y acciones basadas en eventos. Esta guía explica cómo funcionan los webhooks, sus beneficios y cómo configurarlos.
Guía completa sobre webhooks
¿Qué son los webhooks?
Los webhooks son objetos de llamado HTTP que se activan por eventos específicos en un sistema. Cuando ocurre un evento (por ejemplo, un nuevo usuario se registra, se procesa un pago), el sistema envía una solicitud HTTP (generalmente una solicitud POST) a una URL configurada.
Componentes clave de un webhook
Disparador de evento – La acción que hace que el webhook se active (por ejemplo, nuevo pedido realizado).
URL del webhook – El punto final al que se enviará la información.
Carga útil – Los datos que se envían en la solicitud HTTP, típicamente en formato JSON.
Método HTTP – Generalmente
POST, se usa para entregar los datos.Manejo de respuesta – El servidor receptor procesa la solicitud y puede responder con un mensaje de éxito o error.
Cuando ocurre el evento de activación, el cliente de la API de WhatsApp Business detecta, recopila los datos relevantes y envía instantáneamente una solicitud HTTP a la URL del Webhook configurada en la configuración de la aplicación. Esta solicitud actualiza el estado de los mensajes enviados o te notifica cuando se recibe un nuevo mensaje.
Beneficios de usar webhooks
Actualizaciones en tiempo real – Los datos se envían de inmediato en lugar de ser recuperados periódicamente.
Eficientes – Reduce llamadas innecesarias a la API, ahorrando recursos.
Fáciles de implementar – Solo se requiere un endpoint para recibir la información.
Escalables – Funcionan bien para aplicaciones de alto volumen basadas en eventos.
Cómo configurar un webhook
Sigue estos pasos para crear y configurar un webhook:
1. Identificar el disparador de evento
Determina qué acción activará el webhook, como:
Un nuevo registro de usuario
Un pago completado
Una actualización de ticket de soporte
2. Configurar la URL del webhook
Configura un endpoint de servidor para recibir las solicitudes de webhook. Esta URL debe ser accesible públicamente y capaz de manejar solicitudes HTTP POST entrantes.
Ejemplo de URL: https://yourapp.com/webhooks/payment-success
3. Procesar la carga útil del webhook
Tu servidor debe poder analizar y validar los datos entrantes.
Ejemplo de una carga útil JSON:
{ "event": "payment_success", "user_id": 12345, "amount": 100.00, "currency": "USD" }4. Securizar el webhook
Para evitar accesos no autorizados, considera:
Validar firmas de carga útil usando un clave secreta HMAC.
Restringir direcciones IP a fuentes confiables.
Usar HTTPS para transmisión segura.
5. Manejar las respuestas adecuadamente
Tu servidor debe devolver un código de estado HTTP 2xx (200 OK) para confirmar la recepción exitosa. Si ocurre un fallo, el remitente puede reintentar la solicitud.
Ejemplo de respuesta:
{ "status": "success", "message": "Webhook recibido correctamente." }Casos de uso comunes para webhooks
Comercio electrónico: Actualizaciones de estado de pedido
Pagos: Notificaciones de transacción
CRM: Actualizaciones de prospectos e interacciones con clientes
DevOps: Activadores de tuberías CI/CD
Mensajería: Notificaciones de chatbots
Solución de problemas de webhooks
1. Webhook no se activa
Asegúrate de que el disparador del evento se haya configurado correctamente.
Verifica que la URL del webhook sea accesible.
2. Datos de carga útil inválidos
Comprueba el formato de la carga útil y asegúrate de que coincida con las expectativas.
Registra las solicitudes entrantes para depurarlas.
3. Problemas de autenticación
Confirma que las claves de API o las firmas coincidan con los valores esperados.
Usa el registro de eventos para capturar fallos de autenticación.
Detalles adicionales
La puerta de enlace de la API de WhatsApp admite webhooks. Puedes encontrar la documentación aquí.
Para obtener más información sobre los webhooks de WATI, visita Webhooks (wati.io).
Preguntas frecuentes (FAQ)
Preguntas generales
1. ¿Qué son los webhooks?
→ Los webhooks son notificaciones automatizadas que se envían de un sistema a otro cuando ocurren eventos específicos. En lugar de requerir una consulta constante, los webhooks envían actualizaciones en tiempo real mediante solicitudes HTTP.
2. ¿Cómo funcionan los webhooks?
→ Cuando se activa un evento, el sistema recopila los datos relevantes y los envía como una solicitud HTTP POST a una URL de Webhook predefinida. El sistema receptor luego procesa los datos y puede responder con un mensaje de éxito o error.
3. ¿Cuáles son los componentes clave de un webhook?
→ Un webhook consta de:
Disparador de evento – La acción que inicia el webhook (por ejemplo, nuevo pedido, pago completado).
URL del webhook – El endpoint al que se envían los datos.
Carga útil – Los datos enviados en formato JSON.
Método HTTP – Generalmente una solicitud POST.
Manejo de respuesta – El servidor receptor procesa y reconoce la solicitud.
Configurar webhooks
4. ¿Cómo configuro un webhook?
→ Para configurar un webhook:
Identifica el evento que activará el webhook.
Configura una URL de Webhook accesible públicamente.
Asegúrate de que tu servidor pueda procesar los datos entrantes.
Securiza el webhook utilizando métodos de autenticación como firmas HMAC.
Devuelve un código de estado HTTP 2xx para confirmar la recepción.
5. ¿Cómo puedo securizar mi webhook?
→ Para securizar webhooks:
Usa validación de firma HMAC para verificar la integridad de la carga útil.
Restringe las solicitudes a direcciones IP confiables.
Siempre usa HTTPS para transmisión cifrada.
6. ¿Qué debe devolver mi servidor después de recibir un webhook?
→ Tu servidor debe devolver un código de estado HTTP 2xx (por ejemplo, 200 OK) para confirmar la recepción exitosa.
Solución de problemas de webhooks
7. ¿Por qué no se activa mi webhook?
Asegúrate de que el disparador del evento esté configurado correctamente.
Verifica que la URL del webhook esté accesible.
Revisa los registros del servidor para ver errores.
8. ¿Por qué mi webhook devuelve un error de carga útil inválida?
Confirma que el formato de la carga útil coincida con la estructura esperada.
Valida los datos JSON entrantes antes de procesarlos.
Registra las solicitudes recibidas para depurarlas.
9. ¿Qué debo hacer si mi autenticación de webhook falla?
Verifica que las claves de API o las firmas HMAC coincidan con los valores esperados.
Verifica si los encabezados de solicitud contienen los detalles de autenticación correctos.
Activa el registro de eventos para rastrear los fallos de autenticación.
API de WhatsApp e webhooks de WATI
10. ¿La API de WhatsApp Business admite webhooks?
→ Sí, la puerta de enlace de la API de WhatsApp admite webhooks. Puedes encontrar la documentación oficial de webhooks aquí.
11. ¿Dónde puedo aprender más sobre los webhooks de WATI?
→ Para obtener detalles sobre los webhooks de WATI, visita la documentación de Webhooks (wati.io).
12. ¿Por qué fallan mis webhooks en Wati?
→ Los fallos en los webhooks generalmente ocurren porque Wati no recibe una respuesta 200 de tu endpoint de webhook. Asegúrate de que tu URL de webhook esté optimizada para manejar y responder a las solicitudes en 5 segundos. Configura el webhook para enviar un reconocimiento de recepción y procesar los datos del webhook más tarde para evitar fallos.