DocumentaciónAyuda

Activar el webhook y enviar eventos

Obtén la URL y el secreto de firma del webhook y configura tu sistema para que envíe sus eventos a la plataforma.

En esta página

El webhook es la dirección a la que tu sistema envía sus eventos. Cada integración tiene la suya y un Secreto de firma con el que tu sistema firma cada envío. Así la plataforma solo acepta eventos que vienen realmente de tu sistema.

Antes de empezar

  • Necesitas el rol Administrador.

  • La integración debe existir. Si la creaste con Recibir eventos por webhook marcado, el webhook ya está activo y viste el secreto al guardarla.

  • Necesitas a alguien que pueda configurar el sistema externo para que envíe peticiones firmadas.

Activar el webhook

  1. Entra a Configuración → Integraciones.

  2. En la tarjeta de la integración, el campo Webhook dice Desactivado. Presiona Webhook.

  3. Se abre la ventana Webhook activado. No hay confirmación previa: al presionar el botón se generan la URL y el secreto.

Copiar la URL y el secreto

La ventana Webhook activado muestra el aviso Copia el secreto ahora: se muestra una sola vez.

  1. Junto a URL del webhook, presiona Copiar.

  2. Junto a Secreto de firma, presiona Copiar.

  3. Pégalos en la configuración de tu sistema o guárdalos en tu gestor de secretos.

  4. Presiona Ya lo copié, cerrar. En ¿Ya copiaste el secreto?, confirma con Sí, cerrar. Si cierras la ventana de otra forma, también se pide esta confirmación.

La plataforma guarda el secreto cifrado y no puede volver a mostrarlo. Si lo pierdes, tendrás que Rotar o desactivar el webhook y configurar el sistema de nuevo.

Cómo debe enviar los eventos tu sistema

La misma ventana trae las instrucciones en Cómo enviar eventos y ejemplos listos para copiar en las pestañas curl y Node.js (botón Copiar ejemplo). En resumen:

  1. Envía un POST con cuerpo JSON a la URL del webhook.

  2. Agrega el header X-Argunis-Timestamp con la hora actual en segundos Unix.

  3. Agrega el header X-Argunis-Signature: sha256=<firma>, donde la firma es el HMAC-SHA256 en hexadecimal, calculado con el secreto, de timestamp + "." + cuerpo (el cuerpo exacto que envías).

  4. Se rechazan las firmas inválidas o con más de 5 minutos de diferencia con la hora del servidor. Puedes enviar un evento o una lista de eventos (un arreglo JSON).

Cada evento indica su tipo (type: alerta, incidente, activo o vulnerabilidad) y su severidad (severity: baja, media, alta o critica), además de un identificador, un título, cuándo ocurrió y el activo afectado:

{
  "type": "alerta",
  "id": "alert-1234",
  "title": "Múltiples intentos fallidos de RDP",
  "severity": "alta",
  "occurredAt": "2026-09-29T14:05:00Z",
  "asset": {
    "externalId": "agent-017",
    "name": "srv-files",
    "hostname": "srv-files.empresa.local",
    "ip": "10.0.4.30",
    "os": "Windows Server 2022"
  }
}

Envía siempre el id del evento en tu sistema. Si el mismo evento llega dos veces (por un reintento), la plataforma lo reconoce por ese identificador y no lo duplica.

Asegúrate de que el reloj del sistema que envía esté sincronizado. Con más de 5 minutos de diferencia, la plataforma rechaza el envío aunque la firma sea correcta.

Qué pasa después

Cada evento aceptado aparece en la pestaña Eventos recibidos y la tarjeta actualiza Último evento. Según el tipo:

  • Alertas, incidentes, vulnerabilidades y otros eventos entran con estado Nuevo, para que alguien los revise. Un type distinto de los cuatro conocidos se registra como Otro, y una severidad distinta de las cuatro conocidas se ignora.

  • Activos entran siempre con estado Revisado. Si la integración tiene marcado Activos para el inventario, el activo se registra como activo descubierto (o se vincula al que ya tienes con el mismo nombre de equipo o IP). Revisa los nuevos en la pestaña Descubiertos de Empresa → Activos para incorporarlos al inventario. Ver Incorporar o descartar activos descubiertos.

  • Si el evento trae un activo que ya existe en tu inventario (por nombre de equipo o IP), queda vinculado a él.

  • Si la integración tiene Incidente automático, las alertas e incidentes de severidad crítica abren un incidente de inmediato.

Si la integración está Pausada, el webhook no acepta eventos.

Si los eventos no llegan

Pide a quien configura el sistema externo que revise la respuesta que recibe al enviar:

Respuesta

Qué significa

202

El envío se aceptó. Si no lo ves, revisa los filtros de Eventos recibidos.

401, «Firma inválida o vencida.»

El secreto no es el correcto, la firma no se calculó sobre el cuerpo exacto enviado o el reloj del sistema está desfasado más de 5 minutos.

404

La URL no existe: el webhook se rotó o se desactivó, o la integración está Pausada.

429

Demasiados envíos desde la misma dirección (más de 120 por minuto). Agrupa varios eventos en una lista.

Relacionado

Buscar en SofIA Gestión

Escribe al menos 2 letras para buscar en SofIA Gestión.

↑↓ moverse · Enter abrir · Esc cerrar