Webhooks

Admin → Webhooks (/admin/webhooks) suscribe servicios externos a eventos de ARGUS. Cada webhook es un endpoint HTTPS que recibe un POST JSON firmado con HMAC-SHA256 cada vez que uno de los eventos suscritos dispara. Piénsalo como la fontanería cruda debajo de los Workflows — más bajo nivel, pero más simple de conectar a un SIEM, un pipeline de logs, o una consola de ops a medida.

Requiere admin o superadmin.

La lista

Cada tarjeta muestra:

Un punto de estado (verde = enabled, gris = pausado).
El nombre y URL del webhook.
Los chips de evento suscritos.
Un resumen de entrega de una línea — Last delivery: ... más {successCount}/{totalDeliveries} successful.

Acciones de tarjeta (botones de icono a la derecha):

Icono	Acción
Pausar / Reproducir	Alterna `enabled`. Los webhooks pausados mantienen la config pero dejan de despachar.
Historial	Abre el log de entregas.
Editar	Abre el formulario de edición.
Eliminar	Elimina el webhook.

El resumen de cabecera de página dice {webhookCount} configured · {activeCount} active.

Crear / editar

Nuevo webhook (arriba a la derecha) abre el formulario de edición. Campos:

Nombre — etiqueta legible, p. ej. Slack Alert Relay.
URL del endpoint — solo https://. Rechazado si devuelve un redirect.
Secreto de firma (HMAC-SHA256) — auto-generado en la creación; haz clic en el ojo para revelar y en el icono de refrescar para regenerar. Cópialo ahora — las visitas posteriores muestran puntos y solo la cola del secreto. Regenerar invalida cualquier secreto anterior inmediatamente.
Descripción — notas opcionales.
Suscripciones de eventos — cuadrícula de checkboxes agrupada (ver más abajo).
Habilitado — toggle pill.

Guardar escribe a /webhooks/{id} en la raíz de Firestore con un campo orgId. La entrega la maneja el servicio dispatcher de webhooks de argus-api — las reglas de Firestore controlan quién puede escribir el documento, pero el dispatcher es el único código que lo lee.

Catálogo de eventos

Exactamente los 15 valores WebhookEventType, agrupados como la UI los agrupa:

Vuelos — flight.started, flight.completed, flight.failed (RTH, aterrizaje de emergencia, trigger de seguridad).
Alertas — alert.cas (master-caution de Copilot), alert.geofence (brecha de límite), alert.hms (DJI HMS en WARNING+).
IA / Multimedia — detection.new (hit de watchlist en un stream en vivo), media.captured (foto/vídeo subido y catalogado).
Docks — dock.online (primera telemetría), dock.offline (keep-alive expirado).
Operaciones — operation.created / operation.started (transición a active) / operation.completed (cerrada + informe).
Tareas — task.completed, task.failed.

El webhook también lleva una cabecera X-Argus-Event con el tipo de evento para un enrutado trivial.

Firma HMAC

Cada POST lleva la cabecera:

X-Argus-Signature: sha256=<hex>

El <hex> es HMAC_SHA256(secret, <cuerpo crudo de la petición>). Verifícalo antes de confiar en el payload. El sobre del payload es:

{
  "event": "flight.completed",
  "orgId": "org_abc",
  "timestamp": 1745500000000,
  "data": { ... campos específicos del evento ... },
  "idempotencyKey": "flight.completed:flight_xyz:1745500000000"
}

Usa idempotencyKey para deduplicar — la lógica de reintentos del dispatcher puede reenviar el mismo evento (ver más abajo).

Reintentos y backoff

El dispatcher espera un código de estado 2xx dentro de 10 segundos. Cualquier otra cosa (timeout, error de red, 4xx, 5xx) programa un reintento:

Intento 1 — inmediato.
Intento 2 — +1 minuto.
Intento 3 — +5 minutos.

Después de tres fallos el webhook se auto-deshabilita (enabled = false) y un evento admin.webhook.auto_disabled se escribe al log de auditoría. La tarjeta muestra un indicador de pausa rojo; puedes re-habilitarlo después de arreglar el endpoint.

Log de entregas

Haz clic en el icono Historial de una tarjeta de webhook para abrir Delivery log. Cada fila muestra:

Código de estado HTTP (o ERR para errores de red), codificado por color.
El tipo de evento.
Timestamp.
Latencia en ms.
attempt N/3.
Mensaje de error, si lo hay.

Los logs se mantienen 30 días por defecto (configurable por plan — Command y Sovereign lo extienden a 365).