DocumentaciónAjuda

Ativar o webhook e enviar eventos

Obtenha a URL e o segredo de assinatura do webhook e configure o seu sistema para que envie seus eventos à plataforma.

Nesta página

O webhook é o endereço para onde o seu sistema envia seus eventos. Cada integração tem o seu e um Segredo de assinatura com o qual o seu sistema assina cada envio. Assim, a plataforma só aceita eventos que vêm realmente do seu sistema.

Antes de começar

  • Você precisa do papel Administrador.

  • A integração deve existir. Se você a criou com Receber eventos por webhook marcado, o webhook já está ativo e você viu o segredo ao salvá-la.

  • Você precisa de alguém que possa configurar o sistema externo para enviar requisições assinadas.

Ativar o webhook

  1. Acesse Configurações → Integrações.

  2. No cartão da integração, o campo Webhook diz Desativado. Clique em Webhook.

  3. Abre-se a janela Webhook ativado. Não há confirmação prévia: ao clicar no botão, a URL e o segredo são gerados.

Copiar a URL e o segredo

A janela Webhook ativado mostra o aviso Copie o segredo agora: ele é mostrado uma única vez.

  1. Ao lado de URL do webhook, clique em Copiar.

  2. Ao lado de Segredo de assinatura, clique em Copiar.

  3. Cole-os na configuração do seu sistema ou guarde-os no seu gerenciador de segredos.

  4. Clique em Já copiei, fechar. Em Você já copiou o segredo?, confirme com Sim, fechar. Se você fechar a janela de outra forma, essa confirmação também é pedida.

A plataforma guarda o segredo criptografado e não pode mostrá-lo novamente. Se você o perder, terá que Rotacionar ou desativar o webhook e configurar o sistema de novo.

Como o seu sistema deve enviar os eventos

A mesma janela traz as instruções em Como enviar eventos e exemplos prontos para copiar nas abas curl e Node.js (botão Copiar exemplo). Em resumo:

  1. Envie um POST com corpo JSON para a URL do webhook.

  2. Adicione o header X-Argunis-Timestamp com a hora atual em segundos Unix.

  3. Adicione o header X-Argunis-Signature: sha256=<firma>, em que a assinatura é o HMAC-SHA256 em hexadecimal, calculado com o segredo, de timestamp + "." + cuerpo (o corpo exato que você envia).

  4. São rejeitadas as assinaturas inválidas ou com mais de 5 minutos de diferença em relação à hora do servidor. Você pode enviar um evento ou uma lista de eventos (um array JSON).

Cada evento indica seu tipo (type: alerta, incidente, activo ou vulnerabilidad) e sua severidade (severity: baja, media, alta ou critica), além de um identificador, um título, quando ocorreu e o ativo afetado:

{
  "type": "alerta",
  "id": "alert-1234",
  "title": "Múltiplas tentativas de RDP com falha",
  "severity": "alta",
  "occurredAt": "2026-09-29T14:05:00Z",
  "asset": {
    "externalId": "agent-017",
    "name": "srv-files",
    "hostname": "srv-files.empresa.local",
    "ip": "10.0.4.30",
    "os": "Windows Server 2022"
  }
}

Envie sempre o id do evento no seu sistema. Se o mesmo evento chegar duas vezes (por uma nova tentativa), a plataforma o reconhece por esse identificador e não o duplica.

Verifique se o relógio do sistema que envia está sincronizado. Com mais de 5 minutos de diferença, a plataforma rejeita o envio mesmo que a assinatura esteja correta.

O que acontece depois

Cada evento aceito aparece na aba Eventos recebidos e o cartão atualiza Último evento. Conforme o tipo:

  • Alertas, incidentes, vulnerabilidades e outros eventos entram com o status Novo, para que alguém os revise. Um type diferente dos quatro conhecidos é registrado como Outro, e uma severidade diferente das quatro conhecidas é ignorada.

  • Ativos entram sempre com o status Revisado. Se a integração tem marcado Ativos para o inventário, o ativo é registrado como ativo descoberto (ou é vinculado ao que você já tem com o mesmo nome de equipamento ou IP). Revise os novos na aba Descobertos de Empresa → Ativos para incorporá-los ao inventário. Veja Incorporar ou descartar ativos descobertos.

  • Se o evento traz um ativo que já existe no seu inventário (por nome de equipamento ou IP), ele fica vinculado a esse ativo.

  • Se a integração tem Incidente automático, os alertas e incidentes de severidade crítica abrem um incidente imediatamente.

Se a integração está Pausada, o webhook não aceita eventos.

Se os eventos não chegam

Peça a quem configura o sistema externo que verifique a resposta que recebe ao enviar:

Resposta

O que significa

202

O envio foi aceito. Se você não o vê, revise os filtros de Eventos recebidos.

401, «Firma inválida o vencida.»

O segredo não é o correto, a assinatura não foi calculada sobre o corpo exato enviado ou o relógio do sistema está defasado em mais de 5 minutos.

404

A URL não existe: o webhook foi rotacionado ou desativado, ou a integração está Pausada.

429

Envios demais a partir do mesmo endereço (mais de 120 por minuto). Agrupe vários eventos em uma lista.

Relacionado

Pesquisar em SofIA Gestão

Digite pelo menos 2 letras para pesquisar em SofIA Gestão.

↑↓ navegar · Enter abrir · Esc fechar