Puedes encontrar instrucciones de integración más especializadas en la documentación para desarrolladores: Developer Documentation - Webhook Integration Guide
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 sondear la interfaz con frecuencia.Crear un Webhook
1. Añadir un endpoint de Webhook.
Inicia sesión en el panel de YCloud, navega a Developer > Webhooks y haz clic en Add 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 monitorear eventos relevantes.
YCloud ofrece varias opciones de eventos para WhatsApp, SMS, Contact, Email y más.Puedes encontrar todas las cargas útiles relevantes para los eventos aquí: Webhook Payload
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 de firma del endpoint para verificar el encabezado YCloud-Signature. Guarda el secreto de forma segura en tu servidor. Consulta la Webhook Integration Guide para obtener el secreto del endpoint y conocer 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 como
{timestamp}.{request_body}usando exactamente el cuerpo sin procesar de la solicitud. No añadas un punto después del cuerpo. -
Calcula la firma usando el algoritmo HMAC-SHA256:
- Compara la firma calculada con la firma recibida.
4. Responder al Webhook
- Devuelve un código de estado 2xx (por ejemplo, 200, 201, 204)
- Cualquier respuesta que no sea 2xx activará un reintento.
- Respuesta rápida (se recomienda dentro de los 6 segundos)
- Las respuestas rápidas aumentan la prioridad de tu webhook.
- Las respuestas lentas (>10 segundos) pueden perder prioridad.
- Procesamiento asíncrono (recomendado)
- Devuelve inmediatamente 200 OK.
- Procesa los 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 de servidor:8.219.65.7747.236.160.49
La inclusión de IP en listas de permitidos es un control de red adicional. Sigue 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 un evento se envió y solucionar 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 YCloud, ve a Developers > Webhooks.
-
Abre el endpoint de webhook correspondiente y consulta sus registros de entrega.
- Usa uno o más filtros para encontrar el intento de entrega:
- Status: Muestra entregas exitosas o fallidas.
- Event: Filtra por tipo de evento de webhook.
- Event ID: Busca un ID de evento específico de YCloud.
- Data ID: 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 Developers > Webhooks son globales para la cuenta de YCloud. Cuando un evento de cualquier WABA de la cuenta coincide con las suscripciones a eventos configuradas, YCloud lo envía a cada URL de webhook correspondiente. Si necesitas enrutar diferentes WABA a diferentes URL de webhook, usa aplicaciones personalizadas. Una aplicación personalizada te permite asignar números de teléfono específicos de WhatsApp y configurar un endpoint de webhook y suscripciones a eventos específicos 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 deja de reintentar automáticamente ese evento. Tu sistema no recibirá el evento de forma automática una vez que se detengan los reintentos. Una vez restablecido tu servicio, ponte en contacto con el servicio de soporte de YCloud para solicitar una reproducción (replay) de webhooks. La disponibilidad de la reproducció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 reproducirse.Gestión de errores
Mecanismo de reintento:
En caso de que tu servicio devuelva un código de estado distinto de 2xx o no responda, YCloud lo 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: no se volverá a reintentar el evento.
Suspensión de URL:
Para proteger los recursos del sistema, las URL que fallen con frecuencia se suspenderán temporalmente:- Condiciones de activación: 200 fallos por minuto o tiempo acumulado de fallo superior a 10 minutos por minuto
- Duración de la suspensión: 3 minutos
- Durante la suspensión: no se enviará ninguna solicitud de webhook
- Tras la suspensión: restablecimiento automático