Webhooks entrantes

Los webhooks entrantes reciben eventos de otras herramientas y los convierten en tickets o en actualizaciones. Hay tres puntos de entrada:

Origen	Dirección	Configuración en Core
Herramientas de monitorización, DevOps y seguridad	/api/connectors/{vendor}/{tenant}	Integrations, conector del proveedor
Otros ITSM y orígenes REST genéricos	/api/integration/webhook/{integration_id}	Integration Center
Gateway SNMP on-premise	/api/snmp-gateway/trap/{tenant}	Integrations → SNMP gateway

Todas las direcciones están en https://exocortex-api.ai-exo-cortex.com.

Conectores para herramientas de monitorización, DevOps y seguridad

Configuras el conector en exoCortex Core y luego diriges el webhook de la herramienta a la dirección del conector. La herramienta envía su formato nativo: exoCortex lo normaliza y, cuando hace falta, abre un ticket.

Herramientas admitidas:

• Monitorización: Datadog, New Relic, Prometheus, Grafana, Nagios, Icinga, Centreon, Statuspage, NinjaOne.
• DevOps y guardias: GitHub, GitLab, Jenkins, Bitbucket, PagerDuty, Opsgenie.
• Seguridad: Wazuh, Microsoft Sentinel, Tenable, Qualys, Splunk, Elastic, CrowdStrike, SentinelOne, QRadar, Cyber Protect, Fortigate, Check Point y sondas EDR de red.

En la dirección, {vendor} es el nombre de la herramienta en minúsculas (por ejemplo datadog) y {tenant} es el código del tenant para el que has configurado el conector.

Autenticación

• GitHub, GitLab, PagerDuty, Opsgenie y Statuspage firman las solicitudes con su propio mecanismo: exoCortex lo verifica.
• Para todas las demás herramientas usas la firma de exoCortex, calculada con el secreto del conector (consulta Firmar las solicitudes).

Si un conector falla varias veces seguidas, exoCortex suspende temporalmente las solicitudes y responde 503 con resume_in_ms, los milisegundos tras los que debes reintentar.

Integraciones y puentes ITSM

Para ServiceNow, Jira, Zendesk, BMC o un origen REST genérico, configuras la integración en el Integration Center de exoCortex Core, con el mapeo de los campos. El otro sistema envía los eventos a la dirección de la integración; exoCortex los mapea y crea o actualiza el ticket.

La firma es obligatoria cuando la integración tiene un secreto, y las integraciones en modo webhook deben tener uno. Usa la firma de exoCortex; como alternativa se aceptan X-Bridge-Signature, X-Hub-Signature-256 o X-Signature con el valor sha256=<hex HMAC of the body>.

La respuesta es 200 cuando el evento se ha procesado al momento y 202 cuando se ha puesto en cola para un procesamiento fiable.

Firmar las solicitudes

Para firmar una solicitud dirigida a exoCortex, envía dos encabezados:

• X-Exo-Timestamp: la hora actual en segundos Unix;
• X-Exo-Signature: v1= seguido del HMAC-SHA256 hexadecimal de timestamp + "." + body, calculado con el secreto del conector.

exoCortex rechaza las solicitudes con una marca de tiempo que se aleje más de 300 segundos de su hora.

ts=$(date +%s)
body='{"title":"CPU high on web-01","alert_type":"error"}'
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$CONNECTOR_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/connectors/datadog/ACME" \
  -H "Content-Type: application/json" \
  -H "X-Exo-Timestamp: $ts" -H "X-Exo-Signature: v1=$sig" \
  --data-binary "$body"

El encabezado X-NH-Connector-Signature, con el HMAC solo del cuerpo, está obsoleto y funciona hasta el 30 de junio de 2027.

Gateway SNMP

Si tienes equipos que envían traps SNMP, un gateway en tu red las convierte en JSON y las envía a exoCortex. El secreto se define en Integrations → SNMP gateway.

El gateway firma cada solicitud con:

• X-NH-SNMP-Timestamp: la hora actual en milisegundos Unix;
• X-NH-SNMP-Signature: sha256= seguido del HMAC-SHA256 hexadecimal de timestamp + "|" + body.

La tolerancia sobre la hora es de 5 minutos. Un ejemplo de trap:

{
  "source_ip": "192.0.2.10",
  "source_sysname": "core-sw-01",
  "trap_oid": "1.3.6.1.6.3.1.1.5.3",
  "severity": "major",
  "varbinds": {
    "1.3.6.1.2.1.2.2.1.1": "12",
    "1.3.6.1.2.1.2.2.1.2": "GigabitEthernet1/0/12"
  }
}