Webhook in entrata

I webhook in entrata ricevono eventi da altri strumenti e li trasformano in ticket o in aggiornamenti. Ci sono tre punti di ingresso:

Origine	Indirizzo	Configurazione in Core
Strumenti di monitoraggio, DevOps e sicurezza	/api/connectors/{vendor}/{tenant}	Integrations, connettore del fornitore
Altri ITSM e sorgenti REST generiche	/api/integration/webhook/{integration_id}	Integration Center
Gateway SNMP on-premise	/api/snmp-gateway/trap/{tenant}	Integrations → SNMP gateway

Tutti gli indirizzi sono su https://exocortex-api.ai-exo-cortex.com.

Connettori per strumenti di monitoraggio, DevOps e sicurezza

Configuri il connettore in exoCortex Core, poi punti il webhook dello strumento all’indirizzo del connettore. Lo strumento invia il suo formato nativo: exoCortex lo normalizza e, quando serve, apre un ticket.

Strumenti supportati:

• Monitoraggio: Datadog, New Relic, Prometheus, Grafana, Nagios, Icinga, Centreon, Statuspage, NinjaOne.
• DevOps e on-call: GitHub, GitLab, Jenkins, Bitbucket, PagerDuty, Opsgenie.
• Sicurezza: Wazuh, Microsoft Sentinel, Tenable, Qualys, Splunk, Elastic, CrowdStrike, SentinelOne, QRadar, Cyber Protect, Fortigate, Check Point e sonde EDR di rete.

Nell’indirizzo, {vendor} è il nome dello strumento in minuscolo (per esempio datadog) e {tenant} è il codice del tenant per cui hai configurato il connettore.

Autenticazione

• GitHub, GitLab, PagerDuty, Opsgenie e Statuspage firmano le richieste con il loro meccanismo: exoCortex lo verifica.
• Per tutti gli altri strumenti usi la firma di exoCortex, calcolata con il segreto del connettore (vedi Firmare le richieste).

Se un connettore fallisce più volte di seguito, exoCortex sospende temporaneamente le richieste e risponde 503 con resume_in_ms, i millisecondi dopo cui riprovare.

Integrazioni e bridge ITSM

Per ServiceNow, Jira, Zendesk, BMC o una sorgente REST generica configuri l’integrazione nell’Integration Center di exoCortex Core, con la mappatura dei campi. L’altro sistema invia gli eventi all’indirizzo dell’integrazione; exoCortex li mappa e crea o aggiorna il ticket.

La firma è obbligatoria quando l’integrazione ha un segreto, e le integrazioni in modalità webhook devono averne uno. Usa la firma di exoCortex; in alternativa sono accettate X-Bridge-Signature, X-Hub-Signature-256 o X-Signature con valore sha256=<hex HMAC of the body>.

La risposta è 200 quando l’evento è stato elaborato subito, 202 quando è stato messo in coda per un’elaborazione affidabile.

Firmare le richieste

Per firmare una richiesta verso exoCortex invia due intestazioni:

• X-Exo-Timestamp: l’ora attuale in secondi Unix;
• X-Exo-Signature: v1= seguito dall’HMAC-SHA256 esadecimale di timestamp + "." + body, calcolato con il segreto del connettore.

exoCortex rifiuta le richieste con un timestamp che si discosta di più di 300 secondi dalla sua ora.

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"

L’intestazione X-NH-Connector-Signature, con l’HMAC del solo corpo, è deprecata e funziona fino al 30 giugno 2027.

Gateway SNMP

Se hai apparati che inviano trap SNMP, un gateway nella tua rete le converte in JSON e le invia a exoCortex. Il segreto si imposta in Integrations → SNMP gateway.

Il gateway firma ogni richiesta con:

• X-NH-SNMP-Timestamp: l’ora attuale in millisecondi Unix;
• X-NH-SNMP-Signature: sha256= seguito dall’HMAC-SHA256 esadecimale di timestamp + "|" + body.

La tolleranza sull’ora è di 5 minuti. Un esempio di 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"
  }
}