Webhooks de entrada

Os webhooks de entrada recebem eventos de outras ferramentas e transformam-nos em tickets ou em atualizações. Há três pontos de entrada:

Origem	Endereço	Configuração no Core
Ferramentas de monitorização, DevOps e segurança	/api/connectors/{vendor}/{tenant}	Integrations, conector do fornecedor
Outros ITSM e fontes REST genéricas	/api/integration/webhook/{integration_id}	Integration Center
Gateway SNMP on-premises	/api/snmp-gateway/trap/{tenant}	Integrations → SNMP gateway

Todos os endereços estão em https://exocortex-api.ai-exo-cortex.com.

Conectores para ferramentas de monitorização, DevOps e segurança

Configuras o conector no exoCortex Core e depois apontas o webhook da ferramenta para o endereço do conector. A ferramenta envia o seu formato nativo: o exoCortex normaliza-o e, quando necessário, abre um ticket.

Ferramentas suportadas:

• Monitorização: Datadog, New Relic, Prometheus, Grafana, Nagios, Icinga, Centreon, Statuspage, NinjaOne.
• DevOps e on-call: GitHub, GitLab, Jenkins, Bitbucket, PagerDuty, Opsgenie.
• Segurança: Wazuh, Microsoft Sentinel, Tenable, Qualys, Splunk, Elastic, CrowdStrike, SentinelOne, QRadar, Cyber Protect, Fortigate, Check Point e sondas EDR de rede.

No endereço, {vendor} é o nome da ferramenta em minúsculas (por exemplo, datadog) e {tenant} é o código do tenant para o qual configuraste o conector.

Autenticação

• O GitHub, o GitLab, o PagerDuty, o Opsgenie e o Statuspage assinam os pedidos com o seu próprio mecanismo: o exoCortex verifica-o.
• Para todas as outras ferramentas, usas a assinatura do exoCortex, calculada com o segredo do conector (consulta Assinar os pedidos).

Se um conector falhar várias vezes seguidas, o exoCortex suspende temporariamente os pedidos e responde 503 com resume_in_ms, os milissegundos após os quais deves tentar de novo.

Integrações e bridges ITSM

Para ServiceNow, Jira, Zendesk, BMC ou uma fonte REST genérica, configuras a integração no Integration Center do exoCortex Core, com o mapeamento dos campos. O outro sistema envia os eventos para o endereço da integração; o exoCortex mapeia-os e cria ou atualiza o ticket.

A assinatura é obrigatória quando a integração tem um segredo, e as integrações em modo webhook têm de ter um. Usa a assinatura do exoCortex; em alternativa, são aceites X-Bridge-Signature, X-Hub-Signature-256 ou X-Signature com o valor sha256=<hex HMAC of the body>.

A resposta é 200 quando o evento foi processado de imediato e 202 quando foi colocado em fila para um processamento fiável.

Assinar os pedidos

Para assinar um pedido para o exoCortex, envia dois cabeçalhos:

• X-Exo-Timestamp: a hora atual em segundos Unix;
• X-Exo-Signature: v1= seguido do HMAC-SHA256 hexadecimal de timestamp + "." + body, calculado com o segredo do conector.

O exoCortex rejeita os pedidos com um timestamp que se afaste mais de 300 segundos da sua 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"

O cabeçalho X-NH-Connector-Signature, com o HMAC apenas do corpo, está descontinuado e funciona até 30 de junho de 2027.

Gateway SNMP

Se tiveres equipamentos que enviam traps SNMP, um gateway na tua rede converte-as em JSON e envia-as para o exoCortex. O segredo define-se em Integrations → SNMP gateway.

O gateway assina cada pedido com:

• X-NH-SNMP-Timestamp: a hora atual em milissegundos Unix;
• X-NH-SNMP-Signature: sha256= seguido do HMAC-SHA256 hexadecimal de timestamp + "|" + body.

A tolerância sobre a hora é de 5 minutos. Um exemplo 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"
  }
}