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 monitoreo, DevOps y seguridad	/api/connectors/{vendor}/{tenant}	Integrations, conector del proveedor
Otros ITSM y fuentes REST genéricas	/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 monitoreo, DevOps y seguridad

Configuras el conector en exoCortex Core y luego apuntas 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:

• Monitoreo: Datadog, New Relic, Prometheus, Grafana, Nagios, Icinga, Centreon, Statuspage, NinjaOne.
• DevOps y guardias (on-call): 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 configuraste 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 después de los cuales debes reintentar.

Integraciones y bridges ITSM

Para ServiceNow, Jira, Zendesk, BMC o una fuente REST genérica, 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 procesó de inmediato y 202 cuando se puso en cola para un procesamiento confiable.

Firmar las solicitudes

Para firmar una solicitud hacia 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 cuyo timestamp difiere 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, es 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 los convierte a JSON y los envía a exoCortex. El secreto se configura 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 de 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"
  }
}