Events export

Quem investiga um incidente com agente começa no Splunk, no Datadog ou no SIEM da empresa, ao lado dos logs dos outros sistemas. O Events export leva as chamadas dos seus agentes até lá. Cada tool call permitida ou negada, cada token exchange e cada harness login sai do Xokepoint como um evento, com o agente, a pessoa em nome de quem ele agiu, a tool, o resultado e, numa recusa, o código Reference, que leva de volta ao Quick incident.

O export segue a regra do trace: argumentos de tools, valores avaliados, fatos de APIs do cliente e tokens nunca saem num evento.

Onde configurarCopiar link da seção

Account, no menu do perfil, abre a área da conta, e a aba Events export lista os seus destinos. Um destino pertence a quem o cria e cobre os workspaces em que essa pessoa é Admin. Um workspace pode alimentar vários destinos: numa migração de SIEM, as duas ferramentas recebem os mesmos eventos.

A lista mostra, para cada destino, o tipo, os workspaces e ambientes que ele recebe e o status: Delivering, Failing ou Disabled, com a hora da última entrega.

Um destinoCopiar link da seção

O campo Type escolhe o protocolo:

• OpenTelemetry (OTLP) envia log records para um OpenTelemetry Collector ou para um endpoint de fornecedor que aceite OTLP. O Protocol é HTTP/protobuf, em geral na porta 4318, ou gRPC, em geral na 4317. No HTTP, informe a URL base do receptor; os eventos vão para o caminho /v1/logs dele. Um Collector na frente do SIEM alcança a maior parte dos fornecedores pelos exporters que já tem.
• Webhook envia um POST JSON por evento para a sua URL, assinado com um segredo.

Os Headers seguem em toda requisição, por exemplo o token que o SIEM pede. Os valores ficam guardados com criptografia e não aparecem de novo. Ao editar um destino, um header deixado em branco mantém o valor salvo. Use um token que só grave eventos, nunca um token de administrador do SIEM.

What is exported lista os workspaces em que você é Admin. Cada um tem uma chave Production e outra Sandbox, então um workspace pode mandar só Production e outro os dois. Um workspace com as duas chaves desligadas não envia nada.

Send test event manda um evento de amostra, marcado como teste, com o que está no formulário, antes de salvar. A resposta traz o status e o tempo, ou o motivo de não ter chegado.

Regras do endpointCopiar link da seção

• O endpoint usa https.
• O host resolve para um endereço público. O Xokepoint confere o endereço de cada conexão: loopback, rede privada, link-local e endereço de metadata de nuvem são recusados, inclusive quando um nome DNS muda depois do save. Redirects não são seguidos.
• Escreva o host como nome, não como endereço IP: uma URL com IP é recusada ao salvar ou testar.
• Um destino novo não exige nenhuma configuração do lado do Xokepoint: nem allowlist, nem regra de firewall.

O eventoCopiar link da seção

Todo evento tem os mesmos campos, na versão 1 do schema. O webhook manda o evento como corpo JSON:

{
  "schema_version": 1,
  "event_type": "tool_call",
  "event_id": "tool_call_79",
  "time": "2026-11-13T01:31:27.907Z",
  "workspace": { "id": "f1e33718-8e57-411e-9cd2-fc97819f288f", "name": "Acme" },
  "environment": "production",
  "agent": { "id": "f12a1957-8fdc-40fd-a033-46e953955154", "name": "refunds-assistant" },
  "subject": { "kind": "person", "issuer": "https://idp.acme.com", "id": "maria" },
  "server": { "id": "1a2f538d-7b84-425c-a880-87cc1d812282", "name": "Acme Billing" },
  "tool": "refund_order",
  "outcome": "deny",
  "enforcement": "enforce",
  "reason": "no_grant",
  "reference": "abcd-efgh"
}

Um token exchange não tem server, tool nem enforcement. Quando a client assertion falhou, ele vem sem agent; quando a assinatura do subject token não era válida, vem sem subject.

No OTLP, cada evento é um log record. A severidade é INFO para permit e WARN nos outros casos, o event name é xokepoint.tool_call ou xokepoint.token_exchange, o body é uma frase curta, e os campos viram atributos com o prefixo xokepoint., por exemplo xokepoint.agent.name e xokepoint.reference. O resource leva service.name = xokepoint, xokepoint.workspace.id e xokepoint.environment.

Assinatura do webhookCopiar link da seção

A assinatura segue o Standard Webhooks, então qualquer biblioteca dessa especificação faz a verificação. Cada requisição traz três headers:

webhook-id: tool_call_79
webhook-timestamp: 1794533843
webhook-signature: v1,<HMAC-SHA256 em Base64>

O conteúdo assinado é webhook-id, webhook-timestamp e o corpo bruto, unidos por pontos. A chave é o segredo sem o prefixo whsec_, decodificado de Base64. Compare a assinatura em tempo constante e recuse um timestamp com mais de alguns minutos.

O segredo aparece uma vez, logo depois de salvar um webhook novo. Copie nesse momento: o Xokepoint não mostra de novo. Rotate secret cria outro, também exibido uma única vez; requisições assinadas com o segredo antigo param de passar na sua verificação na hora.

Entrega e falhasCopiar link da seção

Os eventos saem em lotes. Quando o destino recusa ou não responde, o Xokepoint tenta outra vez após 10 segundos e dobra a espera a cada falha, até 10 minutos. Um evento que não chega em 72 horas desde o registro é descartado e entra na contagem do destino.

Um destino com falha mostra o status HTTP ou o código gRPC e o host, por exemplo 401 Unauthorized from collector.acme.com ou gRPC Unauthenticated from collector.acme.com. O texto da resposta do seu receptor não é guardado nem exibido. A próxima entrega bem-sucedida devolve o destino para Delivering.

Apagar um destino descarta os eventos que ele ainda não entregou. Apagar um workspace tira esse workspace de todos os destinos; apagar a sua conta apaga os seus destinos.