Puedes encontrar una guía de integración más especializada en la documentación para desarrolladores: Documentación para desarrolladores - Guía de integración de Webhooks
¿Qué es un Webhook?
Un webhook es un mecanismo de devolución de llamada HTTP basado en eventos. Cuando ocurre un evento específico dentro del sistema de YCloud, este envía proactivamente los datos del evento mediante una solicitud HTTPS a una URL preconfigurada (la dirección del webhook), eliminando así la necesidad de realizar consultas periódicas a la interfaz.Crear un Webhook
1. Añadir un endpoint de Webhook.
Inicia sesión en el panel de control de YCloud, ve a Desarrollador > Webhooks y haz clic en Añadir endpoints para crear un endpoint de webhook.
Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.
2. Introduce la dirección del endpoint para monitorizar los eventos relevantes.
YCloud ofrece varias opciones de eventos para WhatsApp, SMS, Contactos, Correo electrónico y más.Puedes encontrar todas las cargas útiles relevantes para los eventos aquí: Carga útil del Webhook
Use Search event to find the subscriptions your endpoint needs.
3. Verificar la firma del webhook
Verifica siempre la firma para asegurarte de que la solicitud proviene de YCloud y no ha sido alterada.
secret para verificar el encabezado YCloud-Signature. Guarda el secreto de forma segura en tu servidor. Consulta la Guía de integración de Webhooks para conocer el secreto del endpoint y el flujo de trabajo de verificación.
Formato de firma:
Algoritmo de verificación:
- Extrae la marca de tiempo (t) y la firma (s) del encabezado de la solicitud (la marca de tiempo es una marca de tiempo Unix en segundos).
-
Construye la carga útil firmada: signed_payload:
{timestamp}.{request_body}. -
Calcula la firma utilizando el algoritmo HMAC-SHA256:
- Compara la firma calculada con la firma recibida.
4. Responder al Webhook
- Devolver un código de estado 2xx (por ejemplo, 200, 201, 204)
- Cualquier respuesta que no sea 2xx activará un reintento.
- Respuesta rápida (recomendado dentro de 6 segundos)
- Las respuestas rápidas aumentan la prioridad de tu webhook.
- Las respuestas lentas (>10 segundos) pueden perder prioridad.
- Procesamiento asíncrono (recomendado)
- Devolver inmediatamente 200 OK.
- Procesa eventos en tareas en segundo plano o colas.
Permitir las IP de entrega de webhooks de YCloud
YCloud envía solicitudes de webhook desde las siguientes direcciones IP del servidor:8.219.65.7747.236.160.49
La lista de permitidos de IP es un control de red adicional. Continúa verificando el encabezado
YCloud-Signature para cada solicitud de webhook.Consultar los registros de entrega de webhooks
YCloud registra los intentos de entrega de webhooks para que puedas confirmar si se envió un evento y solucionar problemas de errores de entrega. Si tu sistema no recibe un webhook esperado, consulta los registros de entrega antes de escalar el problema:- En el panel de control de YCloud, ve a Desarrolladores > Webhooks.
-
Abre el endpoint de webhook correspondiente y consulta sus registros de entrega.
- Utiliza uno o más filtros para encontrar el intento de entrega:
- Estado: Muestra las entregas exitosas o fallidas.
- Evento: Filtra por tipo de evento de webhook.
- ID del evento: Busca un ID de evento específico de YCloud.
- ID de datos: Para eventos de mensajes, introduce el ID del mensaje para encontrar su registro de entrega.
- Selecciona un registro para revisar la hora de entrega, la carga útil de la solicitud, el cuerpo de la respuesta y el código de estado HTTP.
Preguntas frecuentes
Si configuro varias URL de webhook, ¿se enviarán los eventos de cada WABA de la cuenta a todas ellas?
Sí. Los endpoints de webhook configurados en Desarrolladores > Webhooks son globales para la cuenta de YCloud. Cuando un evento de cualquier WABA de la cuenta coincide con las suscripciones de eventos configuradas, YCloud lo envía a cada URL de webhook aplicable. Si necesitas enrutar diferentes WABAs a diferentes URL de webhook, utiliza aplicaciones personalizadas. Una aplicación personalizada te permite asignar números de teléfono de WhatsApp específicos y configurar un endpoint de webhook exclusivo junto con suscripciones de eventos para esa aplicación.¿Qué sucede si fallan los siete intentos de reintento del webhook?
Si tu servicio no se ha recuperado después del séptimo reintento, YCloud dejará de reintentar ese evento automáticamente. Tu sistema no recibirá el evento automáticamente después de que se detengan los reintentos. Después de restablecer su servicio, póngase en contacto con el soporte de YCloud para solicitar una retransmisión de Webhook. La disponibilidad de la retransmisión es limitada: YCloud solo puede reenviar eventos que sigan disponibles en el sistema, y es posible que los eventos históricos más antiguos ya no sean aptos para la retransmisión.Manejo de errores
Mecanismo de reintento:
Si su servicio devuelve un código de estado distinto de 2xx o no responde, YCloud reintentará automáticamente:- Programación de reintentos: 10 segundos → 30 segundos → 5 minutos → 30 minutos → 1 hora → 2 horas → 2 horas.
- Número máximo de reintentos: 7 veces.
- Tras 7 fallos: El evento ya no se volverá a reintentar.
Suspensión de URL:
Para proteger los recursos del sistema, las URL con fallos frecuentes se suspenderán temporalmente:- Condiciones de activación: 200 fallos por minuto o un tiempo acumulado de fallos superior a 10 minutos por minuto
- Duración de la suspensión: 3 minutos
- Durante la suspensión: No se enviarán solicitudes de Webhook
- Tras la suspensión: Restablecimiento automático