Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Webhooks

Recibe llamadas HTTP firmadas cuando cambien dispositivos, alarmas, comandos, firmware y reglas – configuración, firmas, CloudEvents, reintentos, pruebas y la API de webhooks.

Un webhook es una dirección de tu sistema a la que Hermetry llama cuando ocurre un evento. Úsalo para alimentar un sistema de tickets, un ERP, un bus de mensajes o tu propio servicio. Los administradores gestionan los webhooks en Webhooks (en la parte Developer del menú). Enviar webhooks requiere un plan que los incluya.

Crear un webhook

  1. Abre Webhooks y selecciona New Webhook.
  2. Introduce un Name y, opcionalmente, una Description («¿Para qué sirve este webhook?»).
  3. Introduce la URL. Debe ser HTTPS: «Webhook URL must be a valid HTTPS URL.»
  4. En Events, elige al menos un evento. La lista muestra solo los eventos de los módulos que usa tu organización.
  5. Opcionalmente:
    • Custom headers (optional): hasta 20 cabeceras enviadas en cada llamada, por ejemplo un token de autorización que tu receptor comprueba. Content-Type, User-Agent, Host, Content-Length y X-Webhook-* no se pueden definir. Los valores ocupan una línea, con un máximo de 1.000 caracteres.
    • Event filters (optional, advanced): entrega un evento solo cuando su payload coincide (ver más abajo).
    • Tags (optional, comma-separated): etiquetas para organizar tus webhooks, hasta 20.
    • Rate limit (optional, deliveries/minute): vacío significa sin límite.
  6. Guarda. Copia el Signing secret ahora: se muestra una sola vez.

Todos los eventos de los módulos IoT se listan con payloads de ejemplo en la Webhook event reference.

Filtros de eventos

Un filtro de evento es un mapa JSON que va de un evento a los campos del payload que debe cumplir. Una entrega se omite cuando el payload no coincide. Los eventos sin filtro siempre se entregan.

{
  "alarm.created": { "severity": "CRITICAL" },
  "device.disconnected": { "profileId": "6f1c0a2e-0000-4000-8000-000000000001" }
}

Cada ruta nombra un campo de data del evento y puede usar puntos, por ejemplo originator.type. Cada campo indicado debe ser igual a su valor (números y texto se comparan como texto, así que "2" coincide con 2). Como máximo 50 eventos pueden tener filtro.

Así es una entrega

Hermetry envía un POST con estas cabeceras:

CabeceraValor
Content-Typeapplication/json (formato por defecto) o application/cloudevents+json; charset=utf-8
User-AgentHermetry-Webhooks/1.0
X-Webhook-EventEl nombre del evento, por ejemplo device.disconnected
X-Webhook-DeliveryEl id de la entrega. Es el mismo en cada reintento y reenvío de una entrega.
X-Webhook-TimestampSegundos Unix en que se firmó este intento
X-Webhook-Signature-V2sha256= + HMAC-SHA256 de "<timestamp>.<body>" con tu secreto. Usa esta.
X-Webhook-SignatureHMAC-SHA256 solo del body. Forma antigua, mantenida durante un periodo de transición.
X-Webhook-Signature-Prev, X-Webhook-Signature-V2-PrevLo mismo con el secreto anterior, durante una rotación de secreto
X-Webhook-Manualtrue en un evento que un administrador envió manualmente
X-Idempotency-KeyEn los mensajes que un flujo envía con su bloque de webhook

Con el formato por defecto, el body es un envelope:

{
  "webhookId": "…",
  "tenantId": "…",
  "event": "device.disconnected",
  "createdAt": "2026-11-03T12:00:30.000Z",
  "data": { "deviceId": "…", "name": "router-17", "reason": "timeout", "…": "…" }
}

Un evento que un administrador envió manualmente también tiene "manual": true. Responde con cualquier estado 2xx dentro del timeout. Los primeros 4 KB del body de tu respuesta se guardan en el registro de entregas.

Formato CloudEvents

Un endpoint puede recibir CloudEvents 1.0 en modo estructurado. Define "format": "cloudevents" mediante la API (POST o PATCH /api/webhooks/..., ver más abajo). "json" es el valor por defecto.

{
  "specversion": "1.0",
  "id": "8d2c…",
  "source": "urn:hermetry:tenant:<tenantId>",
  "type": "com.hermetry.device.connected",
  "datacontenttype": "application/json",
  "time": "2026-11-03T10:00:30.000Z",
  "data": { "deviceId": "…", "name": "router-17", "transport": "mqtts", "…": "…" },
  "tenantid": "<tenantId>",
  "webhookid": "<webhookId>"
}

data contiene exactamente lo que el formato por defecto contiene bajo data. id es el mismo en cada reintento y reenvío, así que deduplica por source e id. Las cabeceras de firma son las mismas en ambos formatos. Los modos batch y binary no se ofrecen.

Verifica la firma

Verifica contra el body sin procesar, antes de parsearlo, y rechaza timestamps antiguos.

import crypto from 'crypto';

function verifyWebhook(body: string, timestamp: string, signatureV2: string, secret: string): boolean {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  // Reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureV2);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Durante una rotación de secreto, acepta una llamada cuando coincida X-Webhook-Signature-V2 o X-Webhook-Signature-V2-Prev.

Entrega, reintentos y dead letters

AjustePor defectoRango
Request Timeout (ms)15,0001.000 a 120.000
Max Delivery Attempts (incluido el primero)31 a 10
Retry Backoff (ms): la espera antes del reintento 1, 2, …60000,300000,9000001 a 9 valores, cada uno de 1.000 a 86.400.000; más allá de la lista, se usa el último valor
Circuit Breaker Threshold: fallos consecutivos antes de desactivar el endpoint101 a 100.000
Default Rate Limit (per minute): para endpoints sin límite propiosin límitevacío o 0 = sin límite

Defínelos en Webhooks > ajustes (el botón de engranaje). Una entrega está en uno de estos estados: PENDING, SUCCESS, FAILED (se reintentará) o DEAD_LETTERED (se agotaron todos los intentos).

  • Cada entrega se registra con su estado, intentos, código de respuesta, error, duración y hora del siguiente reintento.
  • Un endpoint que supera su límite de frecuencia recibe sus entregas unos 60 segundos más tarde; no se descarta nada.
  • Tras alcanzar el umbral de fallos consecutivos, el endpoint se desactiva y aparece como auto-disabled. Los reintentos en cola se detienen. Vuelve a activarlo para reiniciar el contador y, después, reenvía o reproduce lo que falló.
  • Las entregas son at least once. Deduplica por X-Webhook-Delivery (o por el id de CloudEvents).
  • No se garantiza que los eventos lleguen en orden. Usa las horas del payload.

Los eventos de conexión y de cambio de dispositivos tienen su propio control de volumen: como máximo 600 de cada tipo por organización y minuto por defecto. Consulta la Webhook event reference.

Rotar el secreto

Selecciona Rotate signing secret (rol Owner). El nuevo secreto se muestra una vez. El secreto anterior sigue válido durante 48 horas, y en ese tiempo cada llamada lleva ambas firmas. Rotar de nuevo mientras esa ventana está abierta reemplaza solo el secreto actual; el anterior mantiene su fecha de fin.

Prueba

Desde las acciones de fila de un webhook o desde su página:

  • Send test event envía de inmediato un evento llamado test y muestra el resultado («Test delivered — HTTP 200 in 85 ms»). Una prueba nunca cuenta para el circuit breaker.
  • Trigger event… envía un evento real y firmado que tú eliges, con un payload de ejemplo (objeto JSON, máximo 64 KB), marcado con manual: true y X-Webhook-Manual: true. Respeta el filtro de eventos del endpoint: un ejemplo que el filtro descartaría se rechaza.
  • View deliveries lista las entregas; una entrega fallida o en dead letter puede reenviarse, y todas las dead letters pueden reproducirse a la vez.

Reglas de red

Las direcciones de webhook deben ser direcciones HTTPS públicas. Las direcciones privadas, loopback, link-local y de metadatos de la nube se rechazan al guardar y de nuevo en cada llamada, y no se siguen redirecciones. Para un destino interno intencionado, un administrador puede definir un ipAllowlist explícito (hasta 50 direcciones o rangos CIDR) en el webhook mediante la API.

La API de webhooks

Las rutas cuelgan de /tenant/<tenantId>. Todas requieren los permisos de un administrador.

MétodoRutaFunción
GET/api/webhooks/eventsLos eventos a los que puedes suscribirte
GET, POST/api/webhooksLista (page desde 1, pageSize, search, sort, isActive, autoDisabled); crear: 201 { webhook, secret }
GET, PATCH, DELETE/api/webhooks/{webhookId}Leer, modificar, eliminar
POST/api/webhooks/{webhookId}/rotate-secret{ webhook, newSecret, overlapMs } (Owner)
POST/api/webhooks/{webhookId}/test{ delivery }
POST/api/webhooks/{webhookId}/trigger{ event, payload } → { message, deliveryId }
GET/api/webhooks/{webhookId}/deliveries{ data, total }; filtros status, event, createdFrom, createdTo
POST/api/webhooks/{webhookId}/deliveries/{deliveryId}/redeliverVuelve a encolar una entrega FAILED o DEAD_LETTERED
GET, POST/api/webhooks/{webhookId}/deliveries/replay-dead-letterCuenta, o vuelve a encolar, cada dead letter
GET/api/webhooks/metrics, /api/webhooks/reportEstadísticas de entrega (?webhookId=&days=)

Cuerpo de creación: name, description, url, events, headers, eventFilters, tags, rateLimitPerMinute (de 1 a 100.000), ipAllowlist, format (json o cloudevents).

RechazoSignificado
403 WEBHOOKS_NOT_IN_PLANTu plan no incluye webhooks
409 ENDPOINT_DISABLEDEl endpoint está desactivado; actívalo primero
409 DELIVERY_NOT_REDELIVERABLELa entrega está pendiente o ya se ha realizado correctamente
422 EVENT_FILTERED_OUTEl filtro del endpoint descartaría el evento de prueba que has disparado
422Un evento que ningún módulo de tu organización ofrece