Ir al contenido

Webhooks

Configurás webhooks en el dashboard (Integraciones). Solo se aceptan URLs https públicas (se rechazan destinos privados / SSRF).

En v1 la administración de webhooks es por UI (no hay CRUD vía /public/v1).

Tipo Cuándo Cantidad
Alertas Al crear un evento de regla rota Varios webhooks activos por organización
Digest Snapshot periódico de toda la flota Uno activo por organización (opt-in)

No hay webhook de telemetría por dispositivo.

Al crear un webhook de digest podés:

  • dejar el intervalo de la organización / plataforma (por defecto 900 s = 15 min), o
  • definir un intervalo propio entre 300 s (5 min) y 86400 s (24 h).

Si no hubo telemetría nueva desde el último envío, el digest se omite (no hay POST vacío).

Header Contenido
Content-Type application/json
Content-Encoding gzip en digests grandes (opcional en alertas)
User-Agent AlertIA-Webhook/1.0
X-Alertia-Timestamp Unix time en segundos
X-Alertia-Signature sha256=<hex>
X-Alertia-Idempotency-Key Id único del mensaje

La firma se calcula sobre el JSON en claro (UTF-8), antes de gzip:

HMAC_SHA256(secret, `${timestamp}.${rawBody}`)

El header queda así:

X-Alertia-Signature: sha256=a1b2c3…
  1. Leé el body crudo (bytes) antes de parsear JSON.
  2. Si viene Content-Encoding: gzip, descomprimí después de verificar (la firma es del JSON plano).
  3. Comprobá que |now - timestamp| esté en una ventana corta (p. ej. ±5 minutos).
  4. Recalculá el HMAC con el secret del webhook y compará en tiempo constante.
  5. Deduplicá con X-Alertia-Idempotency-Key (entrega at-least-once: podés recibir reintentos).

Pseudocódigo:

const expected = 'sha256=' + hmacSha256Hex(secret, `${timestamp}.${rawBodyUtf8}`);
if (!timingSafeEqual(expected, signatureHeader)) reject();
POST https://tu-servidor.example/hooks/alertia
Content-Type: application/json
X-Alertia-Timestamp: 1727011200
X-Alertia-Signature: sha256=…
X-Alertia-Idempotency-Key: 8f3c…:a1b2…
{
"type": "alert.created",
"alertEventId": "e7f1a2b3-c4d5-6789-abcd-ef0123456789",
"alertRuleId": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
"deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"deviceName": "Heladera San Martín #01",
"sensorSlug": "temp_cabinet",
"value": 12.5,
"ts": "2026-09-22T12:00:00.000Z",
"webhookId": "w9a8b7c6-d5e4-3210-fedc-ba9876543210"
}
Campo Tipo Descripción
type string Siempre alert.created
alertEventId uuid Evento de alerta
alertRuleId uuid | null Regla que disparó
deviceId uuid Dispositivo
deviceName string | null Nombre al momento del evento
sensorSlug string | null Sensor involucrado
value number | string | null Valor que disparó la alerta
ts string Instantánea ISO-8601
webhookId uuid Webhook destino
{
"type": "telemetry.digest",
"customerId": "c0ffee00-1234-5678-9abc-def012345678",
"webhookId": "w9a8b7c6-d5e4-3210-fedc-ba9876543210",
"generatedAt": "2026-09-22T15:45:00.000Z",
"page": 1,
"pageCount": 1,
"deviceCount": 2,
"devices": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"did": "11111111-2222-3333-4444-555555555555",
"name": "Heladera San Martín #01",
"status": "ONLINE",
"lastSeenAt": "2026-09-22T15:40:12.000Z",
"sensors": [
{
"slug": "temp_cabinet",
"value": 4.2,
"ts": "2026-09-22T15:40:12.000Z",
"unit": "°C"
}
]
}
]
}
Campo Descripción
type telemetry.digest
page / pageCount Paginación si la flota es grande (varios POST)
deviceCount Dispositivos en esta página
devices[].sensors Última métrica conocida por sensor (value / ts / unit pueden ser null)

Los digests suelen enviarse con Content-Encoding: gzip. Timeout de entrega más holgado que el de alertas.

Respondé 2xx lo antes posible. Cualquier otro status puede provocar reintento. La entrega es at-least-once: usá la clave de idempotencia.