Puedes encontrar guías de integración más especializadas 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, envía de forma proactiva los datos del evento mediante una solicitud HTTPS a una URL preconfigurada (la dirección del webhook), eliminando así la necesidad de realizar sondeos frecuentes a la interfaz.Crear un Webhook
1. Añade un endpoint de Webhook.
Inicia sesión en el panel de YCloud, ve a Desarrollador > 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 supervisar eventos relevantes.
YCloud ofrece diversas opciones de eventos para WhatsApp, SMS, Contact, Email y más.Puedes consultar todas las cargas útiles relevantes para los eventos aquí: Carga útil de Webhook
Use Search event to find the subscriptions your endpoint needs.
3. Verifica la firma del webhook
Verifica siempre la firma para asegurarte de que la solicitud proceda de YCloud y no haya sido alterada.
secret de firma del endpoint 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 obtener más detalles sobre el secreto del endpoint y el flujo 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 de Unix en segundos).
-
Construye la carga útil firmada como
{timestamp}.{request_body}utilizando exactamente el cuerpo sin procesar de la solicitud. No añadas un punto después del cuerpo. -
Calcula la firma utilizando el algoritmo HMAC-SHA256:
- Compara la firma calculada con la firma recibida.
4. Responde al Webhook
- Devuelve un código de estado 2xx (p. ej., 200, 201, 204)
- Cualquier respuesta distinta de 2xx activará un reintento.
- Respuesta rápida (se recomienda responder en un plazo 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)
- 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 lista de permitidos de IP es un control de red adicional. Sigue verificando el encabezado
YCloud-Signature para cada solicitud de webhook.Consultar 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 en fallos de entrega. Si tu sistema no recibe un webhook esperado, consulta los registros de entrega antes de escalar la incidencia:- En el panel de YCloud, ve a Developers > Webhooks.
-
Abre el endpoint de webhook relevante y consulta sus registros de entrega.

- Usa uno o más filtros para encontrar el intento de entrega:
- Status: muestra las entregas correctas o fallidas.
- Event: filtra por tipo de evento de webhook.
- Event ID: busca un ID de evento de YCloud específico.
- 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 a todas ellas los eventos de cada WABA de la cuenta?
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 de eventos configuradas, YCloud lo envía a cada URL de webhook aplicable. Si necesitas enrutar diferentes WABA a distintas URL de webhook, usa aplicaciones personalizadas. Una aplicación personalizada te permite asignar números de teléfono de WhatsApp específicos y configurar un endpoint de webhook dedicado y suscripciones a eventos para esa aplicación.¿Qué ocurre 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 ese evento automáticamente. Tu sistema no recibirá el evento de forma automática una vez que se detengan los reintentos. Tras restaurar tu servicio, ponte en contacto con el servicio de soporte de YCloud para solicitar una reproducción (replay) de Webhook. La disponibilidad de la reproducción es limitada: YCloud solo puede reenviar eventos que sigan disponibles en el sistema, y los eventos históricos más antiguos podrían ya no ser aptos para reproducción.Manejo 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: El evento ya no se volverá a reintentar.
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 fallos 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: Restauración automática

