> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real sobre eventos de segurança nos seus repositórios

<h2 id="overview">
  Visão Geral
</h2>

Os webhooks do ZeroPath permitem que você receba notificações HTTP em tempo real quando eventos de segurança importantes ocorrem nos seus repositórios. Isso possibilita criar integrações personalizadas, automatizar fluxos de trabalho e se manter informado sobre sua postura de segurança.

<Card title="Configuração Rápida" icon="bolt" horizontal>
  Configure webhooks nas configurações da sua organização para começar a receber notificações de segurança em tempo real.
</Card>

<h2 id="how-webhooks-work">
  Como os Webhooks Funcionam
</h2>

Quando um evento assinado ocorre, o ZeroPath envia uma requisição HTTP POST para o endpoint configurado com um payload JSON contendo informações detalhadas sobre o evento. Você pode usar esses dados para:

* **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

<h2 id="supported-event-types">
  Tipos de Eventos Suportados
</h2>

O ZeroPath suporta os seguintes tipos de eventos de webhook:

<CardGroup cols={2}>
  <Card title="SCAN_STARTED" icon="play">
    Quando um scan completo de repositório começa
  </Card>

  <Card title="SCAN_COMPLETE" icon="check-circle">
    Quando um scan completo de repositório termina com sucesso
  </Card>

  <Card title="SCAN_FAILED" icon="exclamation-triangle">
    Quando um scan falha ao concluir
  </Card>

  <Card title="SCAN_SCHEDULED" icon="clock">
    Quando um scan é agendado
  </Card>

  <Card title="PR_SCAN_STARTED" icon="code-branch">
    Quando um scan de pull request começa
  </Card>

  <Card title="PR_SCAN_COMPLETE" icon="code-merge">
    Quando um scan de pull request é concluído
  </Card>

  <Card title="NEW_VULNERABILITIES_FULL_SCAN" icon="shield-exclamation">
    Quando novas vulnerabilidades são detectadas em um scan completo de repositório
  </Card>

  <Card title="NEW_VULNERABILITIES_PR" icon="code-pull-request">
    Quando novas vulnerabilidades são detectadas em um pull request
  </Card>

  <Card title="VULNERABILITY_PATCHED" icon="shield-check">
    Quando uma vulnerabilidade é corrigida. Se um único pull request corrigir várias vulnerabilidades, um evento separado é enviado para cada uma.
  </Card>

  <Card title="VULNERABILITY_REOPENED" icon="rotate-left">
    Quando uma vulnerabilidade reaparece
  </Card>

  <Card title="PR_BLOCKED" icon="hand">
    Quando um pull request é bloqueado devido a vulnerabilidades
  </Card>

  <Card title="PR_MERGED_WITH_ISSUES" icon="exclamation-circle">
    Quando um pull request é mesclado na branch principal com vulnerabilidades abertas
  </Card>

  <Card title="REPORT_COMPLETE" icon="file-alt">
    Quando um relatório é gerado
  </Card>

  <Card title="LONG_RUNNING_SCAN" icon="hourglass">
    Quando um scan está demorando mais do que o normal
  </Card>

  <Card title="AUDIT_LOG_EVENT" icon="list">
    Eventos importantes do log de auditoria
  </Card>

  <Card title="SCA_NEW_CVE" icon="shield-virus">
    Quando um novo CVE é detectado em uma dependência do projeto
  </Card>

  <Card title="SCA_NEW_ISSUE" icon="shield-exclamation">
    Quando um novo problema de vulnerabilidade de dependência é criado a partir de qualquer fonte de SCA
  </Card>

  <Card title="INBOUND_WEBHOOK" icon="arrow-right-to-bracket">
    Quando um sistema externo envia um evento para um gatilho de webhook de entrada do ZeroPath
  </Card>

  <Card title="PATCH_PR_DENIED" icon="ban">
    Quando um pull request de correção é negado ou rejeitado
  </Card>

  <Card title="VULNERABILITY_STATUS_CHANGED" icon="arrow-right-arrow-left">
    Quando o status de uma vulnerabilidade muda (por exemplo, de revisão pendente para risco aceito). Disparado para todas as ações de triagem, incluindo arquivar, desarquivar, marcar como verdadeiro positivo, marcar como falso positivo, resolver e desfazer a resolução — sejam elas realizadas pelo dashboard, pela API ou pelo agente de IA do ZeroPath.
  </Card>

  <Card title="SCA_SCAN_STARTED" icon="play">
    Quando um scan de dependências (SCA) começa
  </Card>

  <Card title="SCA_SCAN_COMPLETE" icon="check-circle">
    Quando um scan de dependências (SCA) termina com sucesso
  </Card>

  <Card title="SCA_SCAN_FAILED" icon="exclamation-triangle">
    Quando um scan de dependências (SCA) falha ao concluir
  </Card>

  <Card title="REPO_ADDED" icon="folder-plus">
    Quando um novo repositório é adicionado à organização
  </Card>

  <Card title="RUNTIME_VALIDATION_FINISHED" icon="flask">
    Quando a validação em tempo de execução de uma vulnerabilidade é concluída
  </Card>

  <Card title="RUNTIME_VALIDATION_EXPLOITABLE" icon="bug">
    Quando a validação em tempo de execução confirma que uma vulnerabilidade é explorável
  </Card>

  <Card title="RUNTIME_VALIDATION_NOT_EXPLOITABLE" icon="shield-check">
    Quando a validação em tempo de execução determina que uma vulnerabilidade não é explorável
  </Card>

  <Card title="RUNTIME_VALIDATION_UNABLE" icon="circle-question">
    Quando a validação em tempo de execução não consegue determinar a explorabilidade
  </Card>

  <Card title="CONTAINER_SCAN_STARTED" icon="play">
    Quando um scan de imagem de contêiner começa
  </Card>

  <Card title="CONTAINER_SCAN_COMPLETE" icon="check-circle">
    Quando um scan de imagem de contêiner termina com sucesso
  </Card>

  <Card title="CONTAINER_NEW_ISSUE" icon="shield-exclamation">
    Quando um scan de imagem de contêiner encontra um novo problema
  </Card>

  <Card title="ISSUE_AGED_PAST_THRESHOLD" icon="hourglass-end">
    Quando um problema aberto ultrapassa o limite de tempo configurado
  </Card>

  <Card title="SLA_BURN_RATE_HIGH" icon="gauge-high">
    Quando a taxa de consumo do SLA para problemas abertos está alta
  </Card>
</CardGroup>

<h2 id="webhook-payload-structure">
  Estrutura do Payload do Webhook
</h2>

Todos os payloads de webhook seguem uma estrutura consistente com dados específicos de cada evento:

<h3 id="common-fields">
  Campos Comuns
</h3>

| Campo        | Tipo    | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------ | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `time`       | integer | Sim         | Segundos em epoch Unix de quando o evento foi emitido                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `host`       | string  | Sim         | Host de origem (por exemplo, `zeropath.com`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `source`     | string  | Sim         | Identificador do sistema de origem                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sourcetype` | enum    | Sim         | Tipo de evento. Um de `SCAN_STARTED`, `SCAN_COMPLETE`, `PR_SCAN_STARTED`, `PR_SCAN_COMPLETE`, `NEW_VULNERABILITIES_PR`, `NEW_VULNERABILITIES_FULL_SCAN`, `VULNERABILITY_PATCHED`, `VULNERABILITY_REOPENED`, `AUDIT_LOG_EVENT`, `SCAN_FAILED`, `SCAN_SCHEDULED`, `LONG_RUNNING_SCAN`, `PR_BLOCKED`, `PR_MERGED_WITH_ISSUES`, `REPORT_COMPLETE`, `SCA_NEW_CVE`, `SCA_NEW_ISSUE`, `INBOUND_WEBHOOK`, `PATCH_PR_DENIED`, `VULNERABILITY_STATUS_CHANGED`, `SCA_SCAN_COMPLETE`, `SCA_SCAN_STARTED`, `SCA_SCAN_FAILED`, `REPO_ADDED`, `RUNTIME_VALIDATION_FINISHED`, `RUNTIME_VALIDATION_EXPLOITABLE`, `RUNTIME_VALIDATION_NOT_EXPLOITABLE`, `RUNTIME_VALIDATION_UNABLE`, `CONTAINER_SCAN_STARTED`, `CONTAINER_SCAN_COMPLETE`, `CONTAINER_NEW_ISSUE`, `ISSUE_AGED_PAST_THRESHOLD`, `SLA_BURN_RATE_HIGH` |
| `event`      | object  | Sim         | Objeto de payload do evento contendo os detalhes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

<h3 id="event-object">
  Objeto `event`
</h3>

| Campo                                    | Tipo               | Obrigatório | Descrição                                                                                       |
| ---------------------------------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------- |
| `timestamp`                              | string (date-time) | Sim         | Timestamp ISO 8601 do evento                                                                    |
| `organization`                           | object             | Sim         | Detalhes da organização                                                                         |
| `organization.id`                        | string             | Sim         | ID da organização                                                                               |
| `organization.name`                      | string             | Não         | Nome da organização                                                                             |
| `repository`                             | object             | Não         | Detalhes do repositório                                                                         |
| `repository.id`                          | string             | Sim         | ID do repositório                                                                               |
| `repository.name`                        | string             | Sim         | Nome do repositório                                                                             |
| `scan`                                   | object             | Não         | Detalhes do scan para eventos relacionados a scans                                              |
| `scan.id`                                | string             | Sim         | ID do scan                                                                                      |
| `scan.type`                              | string             | Sim         | Tipo de scan (por exemplo, `FullScan`, `PrScan`)                                                |
| `scan.status`                            | string             | Sim         | Um de `started`, `completed`, `failed`, `scheduled`, `blocked`, `merged_with_issues`, `unknown` |
| `scan.duration_minutes`                  | integer            | Não         | Duração do scan em minutos                                                                      |
| `scan.vulnerability_summary.total`       | integer            | Sim         | Total de vulnerabilidades (quando presente)                                                     |
| `scan.vulnerability_summary.by_severity` | object             | Sim         | Contagens para `critical`, `high`, `medium`, `low`, `info`                                      |
| `scan.url`                               | string             | Sim         | Link para visualizar o scan no ZeroPath                                                         |
| `audit_log`                              | object             | Não         | Presente para `AUDIT_LOG_EVENT`                                                                 |
| `audit_log.id`                           | string             | Sim         | ID do log de auditoria                                                                          |
| `audit_log.endpoint`                     | string             | Sim         | Endpoint da API chamado                                                                         |
| `audit_log.arguments`                    | object             | Não         | Argumentos passados ao endpoint                                                                 |
| `audit_log.caller`                       | object             | Não         | Informações de quem chamou (`id`, `email`)                                                      |
| `audit_log.timestamp`                    | string (date-time) | Sim         | Quando o evento de auditoria ocorreu                                                            |
| `error`                                  | string             | Não         | Mensagem de erro (presente em eventos de falha)                                                 |
| `metadata`                               | object             | Não         | Dados adicionais específicos do evento                                                          |
| `vulnerability`                          | object             | Não         | Informações detalhadas da vulnerabilidade                                                       |

<h3 id="event-specific-requirements">
  Requisitos específicos por evento
</h3>

* `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

<h2 id="event-payload-examples">
  Exemplos de Payload de Eventos
</h2>

<CodeGroup>
  ```json SCAN_COMPLETE theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json SCAN_FAILED theme={null}
  {
    "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"
    }
  }
  ```

  ```json NEW_VULNERABILITIES_FULL_SCAN theme={null}
  {
    "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
      }
    }
  }
  ```

  ```json PR_BLOCKED theme={null}
  {
    "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 }
    }
  }
  ```
</CodeGroup>

<h2 id="configuring-webhooks">
  Configurando Webhooks
</h2>

<CardGroup cols={2}>
  <Card title="Integrations" icon="plug" href="https://zeropath.com/app/settings/integrations">
    Adicione e gerencie endpoints de webhook
  </Card>

  <Card title="Notifications" icon="bell" href="https://zeropath.com/app/settings/notifications">
    Configure quais eventos disparam webhooks
  </Card>
</CardGroup>

<h3 id="setting-up-webhooks">
  Configurando os Webhooks
</h3>

A configuração de webhooks no ZeroPath é um processo de duas etapas que oferece controle granular sobre quais eventos você recebe:

<h4 id="step-1-add-a-webhook-integration">
  Etapa 1: Adicionar uma Integração de Webhook
</h4>

1. Navegue até [zeropath.com/app/settings/integrations](https://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`)

<h4 id="step-2-create-notification-settings">
  Etapa 2: Criar Configurações de Notificação
</h4>

Depois de adicionar uma integração de webhook, configure quais eventos disparam notificações:

1. Acesse [zeropath.com/app/settings/notifications](https://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)

<Info>
  O limite de pontuação de vulnerabilidade só se aplica a eventos relacionados a vulnerabilidades, como `NEW_VULNERABILITIES_FULL_SCAN` e `NEW_VULNERABILITIES_PR`. Outros eventos, como `SCAN_COMPLETE`, sempre serão enviados, independentemente dessa configuração.
</Info>

<Tip>
  O ZeroPath suporta vários canais de notificação. Ao criar uma configuração de notificação, você primeiro selecionará "Webhook" como tipo de canal e depois escolherá entre suas integrações de webhook configuradas. Outros canais de notificação podem incluir e-mail, Slack ou outras integrações.
</Tip>

<h3 id="example-configuration">
  Exemplo de Configuração
</h3>

Aqui está um exemplo de uma configuração típica de webhook:

<Steps>
  <Step title="Criar a Integração de Webhook">
    Adicione um endpoint de webhook em Integrations:

    * Name: "Production Security Alerts"
    * URL: `https://api.example.com/webhooks/zeropath`
    * Custom Headers:
      * `Authorization: Bearer prod-webhook-token-123`
      * `X-Environment: production`
  </Step>

  <Step title="Configurar as Notificações">
    Crie as configurações de notificação:

    * Notification Channel: "Webhook"
    * Webhook: "Production Security Alerts" (da sua lista de webhooks)
    * Repositories: "backend-api", "frontend-app"
    * Events: `NEW_VULNERABILITIES_FULL_SCAN`, `NEW_VULNERABILITIES_PR`, `PR_BLOCKED`
    * Vulnerability Score Threshold: High
  </Step>

  <Step title="Resultado">
    Você receberá webhooks apenas para:

    * Novas vulnerabilidades com pontuação High ou Critical nos repositórios selecionados
    * PRs bloqueados nos repositórios selecionados
    * Nenhuma notificação para vulnerabilidades abaixo do limite High
  </Step>
</Steps>

<h3 id="repository-filtering">
  Filtragem por Repositório
</h3>

Você pode configurar webhooks em diferentes escopos:

<Tabs>
  <Tab title="All Repositories">
    Selecione "All Repositories" para receber notificações de eventos em toda a sua organização. Novos repositórios são incluídos automaticamente.
  </Tab>

  <Tab title="Repositórios Específicos">
    Escolha repositórios individuais para limitar as notificações a projetos específicos. Isso é útil para:

    * Limites de pontuação de vulnerabilidade diferentes por projeto
    * Rotear alertas para equipes diferentes
    * Focar em repositórios críticos
  </Tab>
</Tabs>

<h3 id="vulnerability-score-filtering">
  Filtragem por Pontuação de Vulnerabilidade
</h3>

O limite de pontuação de vulnerabilidade ajuda a reduzir o ruído filtrando vulnerabilidades de menor prioridade. O ZeroPath usa um sistema de pontuação de 0 a 100 categorizado em cinco níveis:

| Nível de Limite | Faixa de Pontuação | Descrição                                  | Caso de Uso Típico                                   |
| --------------- | ------------------ | ------------------------------------------ | ---------------------------------------------------- |
| Critical        | 90-100             | Ação imediata necessária                   | Sistemas de produção, ambientes de tolerância zero   |
| High            | 70-89              | Problemas sérios que exigem atenção rápida | Sistemas importantes, devem ser tratados em breve    |
| Medium          | 40-69              | Vulnerabilidades de risco moderado         | Limite padrão para a maioria dos projetos            |
| Low             | 10-39              | Problemas menores com impacto limitado     | Ambientes de desenvolvimento, qualidade de código    |
| Info            | 0-9                | Achados informativos                       | Trilhas de auditoria, acompanhamento de conformidade |

<Note>
  Quando você seleciona um nível de limite (por exemplo, "High"), receberá notificações para todas as vulnerabilidades nesse nível e acima. Por exemplo, selecionar "High" notificará você sobre vulnerabilidades High e Critical.
</Note>

<h3 id="multiple-webhook-configurations">
  Múltiplas Configurações de Webhook
</h3>

Você pode criar várias integrações de webhook e configurações de notificação para lidar com diferentes cenários. Cada configuração de notificação pode usar o canal "Webhook" com integrações de webhook diferentes:

<CardGroup cols={2}>
  <Card title="Alertas Críticos" icon="bell">
    **Caso de uso**: Notificações imediatas para problemas críticos

    * Webhook: Integração com PagerDuty
    * Repositories: Somente repositórios de produção
    * Events: `NEW_VULNERABILITIES_FULL_SCAN`, `PR_BLOCKED`
    * Vulnerability Score Threshold: Critical
  </Card>

  <Card title="Atualizações da Equipe" icon="users">
    **Caso de uso**: Notificações diárias para a equipe

    * Webhook: Canal do Slack
    * Repositories: Todos os repositórios
    * Events: `SCAN_COMPLETE`, `REPORT_COMPLETE`
    * Vulnerability Score Threshold: Medium
  </Card>

  <Card title="Trilha de Auditoria" icon="list">
    **Caso de uso**: Registro para conformidade

    * Webhook: Sistema SIEM
    * Repositories: Todos os repositórios
    * Events: Todos os tipos de evento
    * Vulnerability Score Threshold: Info (captura tudo)
  </Card>

  <Card title="Fluxo de PRs" icon="code-branch">
    **Caso de uso**: Notificações para desenvolvedores

    * Webhook: GitHub Actions
    * Repositories: Repositórios em desenvolvimento ativo
    * Events: `PR_SCAN_COMPLETE`, `NEW_VULNERABILITIES_PR`
    * Vulnerability Score Threshold: High
  </Card>
</CardGroup>

<h3 id="managing-notification-settings">
  Gerenciando Configurações de Notificação
</h3>

<Tip>
  Você pode criar várias configurações de notificação usando a mesma integração de webhook com configurações diferentes. Isso permite rotear diferentes tipos de eventos ou limites de pontuação de vulnerabilidade para o mesmo endpoint, mas com regras de filtragem diferentes.
</Tip>

Para gerenciar suas configurações de webhook:

1. **Ver todas as configurações**: Navegue até [zeropath.com/app/settings/notifications](https://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

<h3 id="webhook-security">
  Segurança de Webhooks
</h3>

<Warning>
  Sempre use endpoints HTTPS para webhooks a fim de garantir que os dados sejam criptografados em trânsito.
</Warning>

<h4 id="authentication-with-custom-headers">
  Autenticação com Cabeçalhos Personalizados
</h4>

O ZeroPath permite adicionar cabeçalhos personalizados às requisições de webhook para autenticação. Essa abordagem flexível permite implementar uma segurança compatível com a sua infraestrutura:

**Padrões comuns de autenticação:**

```javascript theme={null}
// 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...
});
```

<Tip>
  Você pode adicionar vários cabeçalhos personalizados para reforçar a segurança, como combinar uma chave de API com um timestamp para prevenir ataques de replay.
</Tip>

**Benefícios dos cabeçalhos personalizados:**

* **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

<h2 id="inbound-webhooks-agent-triggers">
  Webhooks de Entrada (Gatilhos do Agente)
</h2>

Além dos webhooks de notificação de saída descritos acima, o ZeroPath suporta **webhooks de entrada** que disparam ações automatizadas do agente. Os webhooks de entrada permitem que sistemas externos enviem eventos ao ZeroPath e que o agente de IA responda com base em um prompt configurável.

<h3 id="how-inbound-webhooks-work">
  Como os Webhooks de Entrada Funcionam
</h3>

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.

<h3 id="use-cases">
  Casos de Uso
</h3>

* **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.

<Info>
  Os webhooks de entrada são gerenciados pelos endpoints da Agent API. Cada gatilho de webhook de entrada inclui um segredo gerado automaticamente para autenticação. Você pode listar, criar, atualizar e excluir gatilhos usando a API V2 ou o servidor MCP.
</Info>

<h2 id="best-practices">
  Boas Práticas
</h2>

<AccordionGroup>
  <Accordion title="Implemente Idempotência">
    Webhooks podem ser entregues mais de uma vez. Use o ID do evento para garantir que cada evento seja processado apenas uma vez.
  </Accordion>

  <Accordion title="Responda Rapidamente">
    Seu endpoint deve retornar um código de status 2xx em até 10 segundos. Processe os dados do webhook de forma assíncrona, se necessário.
  </Accordion>

  <Accordion title="Trate as Novas Tentativas">
    O ZeroPath tentará reenviar entregas de webhook que falharam usando backoff exponencial. Garanta que seu endpoint consiga lidar com eventos duplicados.
  </Accordion>

  <Accordion title="Monitore a Saúde dos Webhooks">
    Configure monitoramento para seus endpoints de webhook para garantir que estejam recebendo e processando eventos corretamente.
  </Accordion>

  <Accordion title="Use a Filtragem de Webhooks">
    Assine apenas os eventos de que você precisa para reduzir ruído e sobrecarga de processamento.
  </Accordion>
</AccordionGroup>

<h2 id="error-handling">
  Tratamento de Erros
</h2>

O ZeroPath usa a seguinte política de novas tentativas para entregas de webhook que falharam:

* **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

<h2 id="need-help">
  Precisa de Ajuda?
</h2>

<Card title="Fale com o Suporte" icon="life-ring" href="mailto:support@zeropath.com">
  Está com problemas nos webhooks? Nossa equipe de suporte está aqui para ajudar.
</Card>

Para informações mais detalhadas sobre a API, consulte nossa [Referência da API](/api-reference/introduction) ou entre na nossa [comunidade no Discord](https://discord.gg/ZRqDvZ6qjJ) para obter ajuda de outros desenvolvedores.