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).
Headers de cada entrega
Sección titulada «Headers de cada entrega»| 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 |
Firma HMAC
Sección titulada «Firma HMAC»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…Verificación recomendada
Sección titulada «Verificación recomendada»- Leé el body crudo (bytes) antes de parsear JSON.
- Si viene
Content-Encoding: gzip, descomprimí después de verificar (la firma es del JSON plano). - Comprobá que
|now - timestamp|esté en una ventana corta (p. ej. ±5 minutos). - Recalculá el HMAC con el
secretdel webhook y compará en tiempo constante. - 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();Alerta — cuerpo de ejemplo
Sección titulada «Alerta — cuerpo de ejemplo»POST https://tu-servidor.example/hooks/alertiaContent-Type: application/jsonX-Alertia-Timestamp: 1727011200X-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 |
Digest periódico — cuerpo de ejemplo
Sección titulada «Digest periódico — cuerpo de ejemplo»{ "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.
Respuesta de tu servidor
Sección titulada «Respuesta de tu servidor»Respondé 2xx lo antes posible. Cualquier otro status puede provocar reintento. La entrega es at-least-once: usá la clave de idempotencia.