Webhooks

​

Visão Geral

​

Como os Webhooks Funcionam

• Automatizar fluxos de trabalho de segurança: Dispare respostas automatizadas a eventos de segurança
• Criar integrações personalizadas: Conecte o ZeroPath às suas ferramentas e plataformas existentes
• Monitorar a postura de segurança: Acompanhe vulnerabilidades e resultados de scans em tempo real
• Aprimorar a conformidade: Registre eventos de segurança para trilhas de auditoria

​

Tipos de Eventos Suportados

​

Estrutura do Payload do Webhook

​

Campos Comuns

​

Objeto event

​

Requisitos específicos por evento

• SCAN_STARTED: event.scan obrigatório
• PR_SCAN_STARTED: event.scan obrigatório
• SCAN_COMPLETE: event.scan obrigatório
• PR_SCAN_COMPLETE: event.scan obrigatório
• SCAN_FAILED: event.scan e event.error obrigatórios
• NEW_VULNERABILITIES_PR: event.vulnerability ou event.scan obrigatório
• NEW_VULNERABILITIES_FULL_SCAN: event.vulnerability ou event.scan obrigatório
• LONG_RUNNING_SCAN: event.metadata.runningMinutes obrigatório
• AUDIT_LOG_EVENT: event.audit_log obrigatório
• SCAN_SCHEDULED: event.metadata com scheduleId, crontab, isEnabled, action obrigatório
• PR_BLOCKED: event.metadata.prId e event.metadata.prNumber obrigatórios
• PR_MERGED_WITH_ISSUES: event.metadata.prUrl e event.metadata.targetBranch obrigatórios
• VULNERABILITY_REOPENED/VULNERABILITY_PATCHED: event.metadata ou event.vulnerability obrigatório. Quando um único pull request corrige várias vulnerabilidades, você receberá um evento VULNERABILITY_PATCHED por vulnerabilidade.
• REPORT_COMPLETE: event.metadata.reportId obrigatório

​

Exemplos de Payload de Eventos

{
  "time": 1729101000,
  "host": "zeropath.com",
  "source": "zeropath",
  "sourcetype": "SCAN_COMPLETE",
  "event": {
    "timestamp": "2025-10-16T12:34:56Z",
    "organization": { "id": "org_123", "name": "Acme Corp" },
    "repository": { "id": "repo_123", "name": "backend-api" },
    "scan": {
      "id": "scan_abc",
      "type": "FullScan",
      "status": "completed",
      "duration_minutes": 8,
      "vulnerability_summary": {
        "total": 3,
        "by_severity": { "critical": 0, "high": 1, "medium": 1, "low": 1, "info": 0 }
      },
      "url": "https://zeropath.com/scans/scan_abc"
    }
  }
}

{
  "time": 1729101200,
  "host": "zeropath.com",
  "source": "zeropath",
  "sourcetype": "SCAN_FAILED",
  "event": {
    "timestamp": "2025-10-16T12:40:00Z",
    "organization": { "id": "org_123", "name": "Acme Corp" },
    "repository": { "id": "repo_123", "name": "backend-api" },
    "scan": { "id": "scan_def", "type": "FullScan", "status": "failed", "url": "https://zeropath.com/scans/scan_def" },
    "error": "Timeout contacting build server"
  }
}

{
  "time": 1729101500,
  "host": "zeropath.com",
  "source": "zeropath",
  "sourcetype": "NEW_VULNERABILITIES_FULL_SCAN",
  "event": {
    "timestamp": "2025-10-16T12:45:00Z",
    "organization": { "id": "org_123", "name": "Acme Corp" },
    "repository": { "id": "repo_123", "name": "backend-api" },
    "vulnerability": {
      "id": "vuln_001",
      "generatedTitle": "SQL Injection risk",
      "severity": 8.2
    }
  }
}

{
  "time": 1729101800,
  "host": "zeropath.com",
  "source": "zeropath",
  "sourcetype": "PR_BLOCKED",
  "event": {
    "timestamp": "2025-10-16T12:50:00Z",
    "organization": { "id": "org_123", "name": "Acme Corp" },
    "repository": { "id": "repo_123", "name": "backend-api" },
    "metadata": { "prId": "01HXYZ", "prNumber": 123 }
  }
}

​

Configurando Webhooks

​

Configurando os Webhooks

​

Etapa 1: Adicionar uma Integração de Webhook

1. Navegue até zeropath.com/app/settings/integrations
2. Clique em “Add Integration” e selecione “Webhook”
3. Configure o endpoint do seu webhook:
   • Name: Um nome descritivo para este webhook
   • URL: Seu endpoint HTTPS que receberá os payloads do webhook
   • Custom Headers: Adicione cabeçalhos personalizados para autenticação (por exemplo, Authorization: Bearer your-secret-token)

​

Etapa 2: Criar Configurações de Notificação

1. Acesse zeropath.com/app/settings/notifications
2. Clique em “Create Notification Setting”
3. Configure suas preferências de notificação:
   • Notification Channel: Selecione “Webhook” entre os canais disponíveis
   • Webhook: Escolha na sua lista de integrações de webhook
   • Repositories: Selecione repositórios específicos ou escolha “All Repositories”
   • Event Types: Selecione quais eventos devem disparar notificações
   • Vulnerability Score Threshold: Para eventos de vulnerabilidade, defina o limite mínimo (Info, Low, Medium, High ou Critical)

​

Exemplo de Configuração

​

Filtragem por Repositório

​

Filtragem por Pontuação de Vulnerabilidade

​

Múltiplas Configurações de Webhook

​

Gerenciando Configurações de Notificação

1. Ver todas as configurações: Navegue até zeropath.com/app/settings/notifications para ver todas as configurações ativas
2. Editar configurações: Clique em qualquer configuração de notificação para modificar repositórios, eventos ou limites de pontuação de vulnerabilidade
3. Ativar/Desativar: Desative notificações temporariamente sem excluir a configuração
4. Testar webhooks: Use o botão “Test” para enviar um payload de exemplo e verificar se seu endpoint está funcionando

​

Segurança de Webhooks

​

Autenticação com Cabeçalhos Personalizados

// Example 1: Bearer Token
// Custom Header: Authorization: Bearer your-secret-token

app.post('/webhooks/zeropath', (req, res) => {
  const authHeader = req.headers['authorization'];
  if (authHeader !== 'Bearer your-secret-token') {
    return res.status(401).send('Unauthorized');
  }
  // Process webhook...
});

// Example 2: API Key
// Custom Header: X-API-Key: your-api-key

app.post('/webhooks/zeropath', (req, res) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.WEBHOOK_API_KEY) {
    return res.status(401).send('Invalid API key');
  }
  // Process webhook...
});

// Example 3: Custom Secret Header
// Custom Header: X-Webhook-Secret: your-webhook-secret

app.post('/webhooks/zeropath', (req, res) => {
  const secret = req.headers['x-webhook-secret'];
  if (secret !== process.env.ZEROPATH_WEBHOOK_SECRET) {
    return res.status(401).send('Invalid webhook secret');
  }
  // Process webhook...
});

• Flexibilidade: Use qualquer esquema de autenticação que se adapte à sua infraestrutura
• Compatibilidade: Funciona com gateways de API e middlewares de autenticação existentes
• Múltiplos cabeçalhos: Adicione vários cabeçalhos para propósitos diferentes (autenticação, roteamento, metadados)
• Padrões consolidados: Use padrões de autenticação consagrados do mercado, como tokens Bearer

​

Webhooks de Entrada (Gatilhos do Agente)

​

Como os Webhooks de Entrada Funcionam

1. Você cria um gatilho de evento com o tipo de evento INBOUND_WEBHOOK via API ou servidor MCP.
2. O ZeroPath gera uma URL de webhook e um segredo únicos para o gatilho:
   https://zeropath.com/api/agent/webhook/{triggerId}?secret={webhookSecret}
   
3. Quando um sistema externo envia um HTTP POST para essa URL, o agente executa o prompt do gatilho com o payload do webhook disponível como contexto.
4. Você pode visualizar o histórico de execuções e os resultados do gatilho por meio da API.

​

Casos de Uso

• Integração com CI/CD externo: Dispare o agente para triar achados quando seu pipeline de build for concluído.
• Integração com ferramentas de terceiros: Faça com que ferramentas de segurança externas enviem achados ao agente para análise automatizada.
• Automação personalizada: Conecte qualquer sistema capaz de enviar requisições HTTP POST para disparar fluxos de trabalho do agente.

​

Boas Práticas

​

Tratamento de Erros

• Primeira nova tentativa: 30 segundos após a primeira falha
• Tentativas subsequentes: Backoff exponencial (1min, 2min, 4min, 8min, 16min)
• Máximo de tentativas: 6 tentativas ao longo de ~30 minutos
• Ação final: Webhook marcado como falho e notificação enviada

​

Precisa de Ajuda?