Resumen
Los webhooks son una forma en que las aplicaciones envían datos en tiempo real a otros sistemas cuando ocurren eventos específicos. A diferencia de las API tradicionales que requieren una consulta constante, los webhooks envían actualizaciones automáticamente, lo que los hace eficientes para notificaciones y acciones impulsadas por eventos. Esta guía explica cómo funcionan los webhooks, sus beneficios y cómo configurarlos.
Webhooks: Una guía completa
¿Qué son los webhooks?
Los webhooks son llamadas de retorno HTTP desencadenadas 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 se active el webhook (por ejemplo, nuevo pedido realizado).
URL del webhook – El punto de conexión donde se enviarán los datos.
Carga útil – Los datos enviados en la solicitud HTTP, generalmente en formato JSON.
Método HTTP – Generalmente
POST, utilizado para entregar los datos.Control de respuestas – El servidor receptor procesa la solicitud y puede responder con un mensaje de éxito o error.
Cuando se produce el evento desencadenante, el cliente de la API de WhatsApp Business detecta el evento, 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 instantáneamente en lugar de ser extraídos periódicamente.
Eficiente – Reduce las llamadas de API innecesarias, ahorrando recursos.
Fácil de implementar – Solo requiere un punto de conexión para recibir los datos.
Escalable – Funciona bien para aplicaciones impulsadas por eventos de alto volumen.
Cómo configurar un webhook
Siga estos pasos para crear y configurar un webhook:
1. Identificar el disparador de evento
Determinar qué acción desencadenará el webhook, como:
Un nuevo registro de usuario
Un pago completado
Una actualización de ticket de soporte
2. Configurar la URL del webhook
Configurar un punto de conexión del servidor para recibir solicitudes de webhook. Esta URL debe ser accesible públicamente y capaz de manejar solicitudes HTTP entrantes POST.
URL de ejemplo:https://yourapp.com/webhooks/payment-success
3. Procesar la carga útil del webhook
Su servidor debe poder analizar y validar los datos entrantes.
Ejemplo de carga útil JSON:
{
"evento": "payment_success",
"id_de_usuario": 12345,
"monto": 100.00,
"divisa": "USD"
}4. Proteger el webhook
Para evitar el acceso no autorizado, considere:
Validar firmas de carga útil utilizando una clave secreta HMAC.
Restringir direcciones IP a fuentes de confianza.
Usar HTTPS para transmisión segura.
5. Manejar respuestas adecuadamente
Su servidor debe devolver un código de estado HTTP 2xx (200 OK) para confirmar la recepción exitosa. Si ocurre un error, el remitente puede volver a intentar la solicitud.
Respuesta de ejemplo:
{
"estado": "éxito",
"mensaje": "Webhook recibido con éxito."
}Casos de uso comunes para webhooks
Comercio electrónico: Actualizaciones de estado de pedido
Pagos: Notificaciones de transacciones
CRM: Actualizaciones de leads y interacciones de clientes
DevOps: Disparadores de canalizaciones de CI/CD
Mensajería: Notificaciones de chatbot
Solución de problemas de webhooks
1. Webhook no se dispara
Asegúrese de que el disparador de evento esté configurado correctamente.
Verifique que la URL del webhook sea accesible.
2. Datos de carga útil no válidos
Verifique el formato de la carga útil y asegúrese de que coincida con las expectativas.
Registre las solicitudes entrantes para depuración.
3. Problemas de autenticación
Confirme que las claves de API o firmas coincidan con los valores esperados.
Utilice el registro para capturar fallas de autenticación.
Detalles adicionales
La Puerta de Enlace de la API de WhatsApp admite webhooks. Puede encontrar la documentación aquí.
Para obtener más información sobre los webhooks de WATI, visite la documentación de Webhooks (wati.io).
Preguntas Frecuentes (FAQ)
Preguntas Generales
1. ¿Qué son los webhooks?
Los webhooks son notificaciones automatizadas enviadas desde un sistema a otro cuando ocurren eventos específicos. En lugar de requerir una consulta constante, los webhooks envían actualizaciones en tiempo real utilizando solicitudes HTTP.
2. ¿Cómo funcionan los webhooks?
Cuando se produce 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 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 consiste en:
Disparador de evento – La acción que inicia el webhook (por ejemplo, nuevo pedido, pago completado).
URL del webhook – El punto de conexión donde se envían los datos.
Carga útil – Los datos enviados en formato JSON.
Método HTTP – Generalmente una solicitud POST.
Control de respuestas – El servidor receptor procesa y reconoce la solicitud.
Configuración de Webhooks
4. ¿Cómo configuro un webhook?
Para configurar un webhook:
Identifique el evento que desencadenará el webhook.
Configure una URL de webhook accesible públicamente.
Asegúrese de que su servidor pueda procesar los datos entrantes.
Proteja el webhook utilizando métodos de autenticación como firmas HMAC.
Devuelva un código de estado HTTP 2xx para confirmar la recepción.
5. ¿Cómo puedo proteger mi webhook?
Para proteger los webhooks:
Utilice validación de firmas HMAC para verificar la integridad de la carga útil.
Restringa las solicitudes a direcciones IP de confianza.
Utilice siempre HTTPS para transmisión segura.
6. ¿Qué debería devolver mi servidor después de recibir un webhook?
Su 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é mi webhook no se dispara?
Asegúrese de que el disparador de evento esté configurado correctamente.
Verifique que la URL del webhook sea accesible.
Verifique los registros del servidor para errores.
8. ¿Por qué mi webhook devuelve un error de carga útil no válida?
Confirme que el formato de la carga útil coincida con la estructura esperada.
Valide los datos JSON entrantes antes de procesarlos.
Registre las solicitudes recibidas para depuración.
9. ¿Qué debo hacer si mi autenticación de webhook falla?
Verifique que las claves de API o firmas HMAC coincidan con los valores esperados.
Verifique si los encabezados de la solicitud contienen los detalles de autenticación correctos.
Habilite el registro para rastrear fallas de autenticación.
API de WhatsApp y Webhooks de WATI
10. ¿La API de WhatsApp Business admite webhooks?
Sí, la Puerta de Enlace de la API de WhatsApp admite webhooks. Puede encontrar la documentación oficial de webhooks aquí.
11. ¿Dónde puedo obtener más información sobre los webhooks de WATI?
Para obtener detalles sobre los webhooks de WATI, visite la documentación de Webhooks (wati.io).
12. ¿Por qué mis webhooks fallan en Wati?
Los fallos de webhooks generalmente ocurren porque Wati no recibe un código de estado 200 desde su punto de conexión de webhook. Asegúrese de que su URL de webhook esté optimizada para manejar y responder a solicitudes dentro de 5 segundos. Configure el webhook para enviar un acuse de recibo y procese los datos del webhook más adelante para evitar fallos.