Webhooks

Los webhooks conectan dAio con sus propios sistemas. En lugar de consultar la plataforma de forma continua, deja que dAio le avise: en cuanto se produce un evento — una alerta meteorológica activada, un riesgo elevado detectado — dAio envía en tiempo real una solicitud HTTP firmada al endpoint que elija. Así automatiza sus flujos de trabajo: apertura de tickets, notificaciones internas, actualización de un cuadro de mando de negocio o activación de un plan de acción sobre el terreno.

Es el puente entre las alertas de dAio y su sistema de información.

Consejo : empiece con un único webhook suscrito a un solo tipo de evento, valide la cadena de principio a fin y luego amplíe. Evitará saturar sus sistemas con notificaciones antes de haber fiabilizado el procesamiento.

Configurar un webhook

1. Acceda a Ajustes > Webhooks.
2. Haga clic en Nuevo webhook.
3. Indique la URL de destino: el endpoint HTTPS de su servidor (p. ej. https://votre-serveur.com/webhook).
4. Seleccione los eventos que desea escuchar haciendo clic en las etiquetas correspondientes.
5. Confirme con Crear.

Al crearlo se genera automáticamente un secreto. Sirve para firmar cada solicitud con HMAC-SHA256 (véase más abajo): consérvelo en el lado del servidor, ya que le permite verificar que cada llamada procede realmente de dAio.

Atención : la URL debe ser HTTPS y accesible públicamente. Un endpoint en HTTP simple o detrás de un cortafuegos cerrado no podrá recibir las entregas.

Eventos disponibles

Evento	Descripción
weather.alert	Se ha activado una alerta meteorológica en un sitio
weather.threshold	Se ha superado un umbral meteorológico personalizado
air_quality.alert	Se ha emitido una alerta de calidad del aire
pollen.alert	Se ha emitido una alerta de polen
marine.alert	Se ha emitido una alerta de condiciones marinas
frost.alert	Se ha activado una alerta de helada
storm.alert	Se ha activado una alerta de tormenta / temporal
business.risk_high	Se ha detectado un nivel de riesgo elevado para su actividad

Consejo : suscriba cada webhook únicamente a los eventos que realmente utiliza el sistema destinatario. Un endpoint de «tickets» no necesita recibir los mismos eventos que un endpoint de «cuadro de mando».

Formato del payload

Cada entrega es una solicitud POST cuyo cuerpo es un objeto JSON. La estructura general es la siguiente:

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

El campo event identifica el tipo de evento, timestamp indica la fecha de emisión (UTC, formato ISO 8601) y data contiene los detalles propios del evento.

Autenticación HMAC-SHA256

Cada solicitud se firma con su secreto mediante HMAC-SHA256. La firma se transmite en la cabecera X-Daio-Signature, con el formato sha256=<signature>.

Verifique sistemáticamente esta firma antes de procesar una solicitud: es lo que garantiza que la llamada procede de dAio y que el payload no ha sido alterado.

Verificación en el lado del servidor (Python):

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Atención : calcule la firma sobre el cuerpo bruto de la solicitud (los bytes recibidos), antes de cualquier deserialización JSON. El más mínimo reformateo modifica el hash y hace que falle la verificación.

Probar y depurar

• Haga clic en el icono Probar (▶) junto a un webhook para enviar un evento ficticio a su endpoint.
• Una respuesta HTTP 2xx confirma que su servidor ha recibido y aceptado la solicitud.
• Despliegue el webhook para consultar sus últimas entregas: código HTTP, tipo de evento y marca de tiempo.
• Un punto de color indica el estado del webhook: verde = activo, rojo = desactivado tras fallos repetidos.

Historial de entregas

Cada envío se registra. Despliegue un webhook para ver, en cada intento:

• El código HTTP de respuesta (verde si < 300, rojo en caso contrario)
• El tipo de evento entregado
• La fecha y la hora del intento

Aparece un contador de fallos en el webhook cuando alguna entrega ha fallado.

Reintentos y fiabilidad

dAio reintenta automáticamente la entrega en caso de fallo, con intervalos crecientes. Por tanto, su endpoint debe ser idempotente: una misma entrega puede llegar varias veces, y su procesamiento debe producir el mismo resultado sin efectos secundarios.

Atención : su endpoint debe responder en menos de 10 segundos con un código HTTP 2xx. Más allá de ese plazo, o en caso de código de error, la entrega se considera fallida y se reintentará. Tras fallos repetidos, el webhook se desactiva automáticamente.

Buenas prácticas

• Verifique siempre la firma HMAC antes de procesar un payload: nunca confíe en una solicitud no autenticada.
• Responda rápido: devuelva un 200 de inmediato y luego procese la carga de trabajo en segundo plano. Evitará tiempos de espera y reintentos innecesarios.
• Haga su procesamiento idempotente para absorber sin riesgo las entregas múltiples.
• Filtre en el origen: suscriba cada webhook solo a los eventos útiles para su sistema destinatario.
• Vigile el contador de fallos y el historial de entregas para detectar rápidamente un endpoint averiado antes de que se desactive.
• Use el botón Probar después de cada cambio por su parte (despliegue, cambio de URL) para validar la cadena sin esperar a un evento real.

Consejo : combine sus webhooks con las alertas y la configuración de su equipo para encaminar automáticamente la información correcta hacia el sistema correcto. La disponibilidad de los webhooks depende de su suscripción.