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

# Configuração de Webhook

> Guia passo a passo para configurar webhooks no seu dashboard Gu1 — com eventos webhook gu1 para integração downstream em tempo real.

## Visão Geral

Este guia orienta você na configuração de webhooks no seu dashboard Gu1. Os webhooks são configurados no **nível da organização** e se aplicam a todos os eventos que correspondem aos seus filtros.

## Pré-requisitos

Antes de configurar webhooks, você precisa:

* ✅ Uma conta Gu1 ativa com permissões de administrador
* ✅ Um endpoint HTTPS publicamente acessível para receber webhooks

Você **não** precisa fornecer um secret de webhook. O Gu1 **gera automaticamente** um secret ao criar um webhook. O dashboard **mostra o secret uma vez** logo após criar (ou regenerar) o webhook—copie-o aí; ele não será mostrado novamente na lista de webhooks. **Seus webhooks receberão eventos mesmo se você não verificar a assinatura**; verificar a assinatura (usando o secret e o header `X-Webhook-Signature`) é opcional, mas recomendado para que seu endpoint possa confirmar que a requisição veio do Gu1. O payload do **monitor de webhooks** é apenas para debug: a verificação deve usar o **raw body HTTP** no recebimento; veja [Segurança de webhooks](/pt/webhooks/security#falhas-intermitentes-de-assinatura).

<Note>
  Para desenvolvimento local, use ferramentas como [ngrok](https://ngrok.com/) para criar uma URL pública que faz túnel para seu servidor local.
</Note>

## Configuração Passo a Passo

### Passo 1: Navegar para Configurações de Webhooks

1. Faça login no seu dashboard Gu1 em [app.gu1.ai](https://app.gu1.ai)
2. Vá para **Configurações** → **Webhooks**
3. Clique em **Adicionar Webhook** ou **Criar Webhook**

### Passo 2: Informações Básicas

<Steps>
  <Step title="Nomear seu webhook">
    Digite um nome descritivo para identificar este webhook

    **Exemplos**:

    * "Webhook KYC de Produção"
    * "Eventos de Entidade Sandbox"
    * "Monitoramento de Conformidade"
  </Step>

  <Step title="Adicionar descrição (opcional)">
    Adicione notas sobre para que este webhook é usado

    **Exemplo**: "Envia eventos de aprovação de KYC para nosso sistema CRM"
  </Step>

  <Step title="Inserir URL do webhook">
    Forneça a URL do endpoint HTTPS que receberá solicitações POST

    **Requisitos**:

    * Deve usar HTTPS (não HTTP)
    * Deve ser publicamente acessível
    * Deve retornar status 200 dentro de 30 segundos

    **Exemplo**: `https://api.seuapp.com/webhooks/gu1`
  </Step>
</Steps>

### Passo 3: Selecionar Ambiente

Escolha a qual ambiente este webhook se aplica:

<Tabs>
  <Tab title="Sandbox">
    **Use para**:

    * Desenvolvimento e testes
    * Ambientes de staging
    * Processos de QA

    **Recebe**:

    * Eventos de chamadas de API sandbox
    * Validações e transações de teste
  </Tab>

  <Tab title="Produção">
    **Use para**:

    * Sistemas de produção ao vivo
    * Dados reais de clientes
    * Fluxos de trabalho críticos

    **Recebe**:

    * Eventos de chamadas de API de produção
    * Verificações reais de clientes
  </Tab>
</Tabs>

<Note>
  Você pode criar webhooks separados para sandbox e produção com URLs diferentes. Isso permite testes seguros sem afetar sistemas de produção.
</Note>

### Passo 4: Inscrever-se em Eventos

Selecione quais tipos de eventos acionam este webhook:

#### Opção A: Inscrever-se em Todos os Eventos de uma Categoria

* `entity.*` - Todos os eventos de entidade
* `kyc.*` - Todos os eventos de validação KYC
* `rule.*` - Todos os eventos de regras
* `transaction.*` - Todos os eventos de transação (em breve)
* `alert.*` - Todos os eventos de alerta (em breve)

#### Opção B: Inscrever-se em Eventos Específicos

Selecione eventos individuais:

**Eventos de Entidades**:

* ☐ `entity.created`
* ☐ `entity.updated`
* ☐ `entity.status_changed`
* ☐ `entity.deleted` (em breve)

**Eventos KYC**:

* ☐ `kyc.validation_created`
* ☐ `kyc.validation_in_progress`
* ☐ `kyc.validation_approved`
* ☐ `kyc.validation_rejected`
* ☐ `kyc.validation_abandoned`
* ☐ `kyc.validation_expired`

**Eventos de Regras**:

* ☐ `rule.triggered`

<Tip>
  Comece com eventos específicos que você precisa, depois expanda conforme construir mais integrações. Você sempre pode atualizar as inscrições mais tarde.
</Tip>

### Passo 5: Configurar Filtros (Opcional)

Adicione filtros para receber apenas eventos relevantes:

<Accordion title="Filtrar por Tipo de Entidade">
  Acione webhook apenas para tipos de entidades específicos:

  **Opções**:

  * Pessoa
  * Empresa
  * Dispositivo
  * Método de Pagamento

  **Exemplo**: Receber apenas eventos para entidades de pessoa, ignorar empresas
</Accordion>

<Accordion title="Filtrar por Mudanças de Status">
  Acione apenas quando mudanças de status corresponderem a critérios específicos:

  **Status De**: Acione apenas quando mudar DESTE status

  * `under_review`
  * `active`
  * `blocked`
  * `pending`

  **Status Para**: Acione apenas quando mudar PARA este status

  * `active`
  * `blocked`
  * `archived`

  **Exemplo**: Acione apenas quando entidades forem mudadas PARA status `blocked`
</Accordion>

<Accordion title="Filtrar por Flag de Cliente">
  Filtre eventos baseados na flag `isClient` da entidade:

  **Opções**:

  * Apenas clientes (`isClient: true`)
  * Apenas não-clientes (`isClient: false`)
  * Todas as entidades (sem filtro)

  **Exemplo**: Receber apenas eventos para entidades marcadas como clientes
</Accordion>

### Passo 6: Configurar Política de Tentativas (Opcional)

Personalize como Gu1 lida com entregas de webhook falhadas:

```json theme={null}
{
  "maxRetries": 3,
  "retryDelayMs": 1000,
  "backoffMultiplier": 2
}
```

**Parâmetros**:

* `maxRetries` - Máximo de tentativas de repetição (padrão: 3)
* `retryDelayMs` - Atraso inicial antes da primeira tentativa (padrão: 1000ms)
* `backoffMultiplier` - Multiplicador para backoff exponencial (padrão: 2)

**Linha do tempo de exemplo com padrões**:

1. Tentativa inicial em T+0s
2. Primeira tentativa em T+1s (1000ms)
3. Segunda tentativa em T+3s (1000ms × 2)
4. Terceira tentativa em T+7s (1000ms × 2 × 2)

<Tip>
  A política de tentativas padrão funciona bem para a maioria dos casos de uso. Personalize apenas se tiver requisitos específicos.
</Tip>

### Passo 7: Adicionar Headers Personalizados (Opcional)

Adicione headers HTTP personalizados às solicitações de webhook:

**Casos de uso comuns**:

* Tokens de autorização: `Authorization: Bearer token123`
* Chaves de API: `X-API-Key: your-api-key`
* Identificadores personalizados: `X-Webhook-Source: gu1`

**Formato**:

```json theme={null}
{
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-key",
  "X-Custom-Header": "custom-value"
}
```

<Warning>
  Evite enviar secrets sensíveis em headers personalizados. Use verificação de assinatura em vez disso para autenticação.
</Warning>

### Passo 8: Copiar o Secret Gerado

Você não precisa fornecer um secret ao criar o webhook. Após salvar, o Gu1 gera automaticamente um secret e **o dashboard o exibe uma vez** na etapa de sucesso ao criar. Copie-o aí—ele não será exibido novamente na lista de webhooks (você pode regenerar um novo depois nas configurações do webhook, se precisar).

<Steps>
  <Step title="Copiar o secret">
    **IMPORTANTE**: Copie e salve este secret imediatamente. Você não poderá vê-lo novamente na lista.

    O secret se parece com: `whsec_abc123def456...`
  </Step>

  <Step title="Armazenar com segurança">
    Salve o secret nas suas variáveis de ambiente ou gerenciador de secrets:

    ```bash theme={null}
    # arquivo .env
    GU1_WEBHOOK_SECRET=whsec_abc123def456...
    ```
  </Step>

  <Step title="Usar para verificação (opcional)">
    Use este secret para verificar assinaturas de webhook no seu endpoint (header `X-Webhook-Signature`). **A verificação é opcional**: seu webhook receberá eventos mesmo se você não verificar; verificar é recomendado por segurança.

    [Saiba sobre verificação de assinatura →](/pt/webhooks/security)
  </Step>
</Steps>

<Warning>
  Nunca faça commit de secrets de webhook no controle de versão. Sempre use variáveis de ambiente ou um gerenciador de secrets.
</Warning>

### Passo 9: Habilitar Webhook

Alterne o webhook para status **Habilitado**:

* ✅ **Habilitado** - Webhook recebe eventos ativamente
* ⏸️ **Desabilitado** - Webhook pausado, nenhum evento enviado

Você pode desabilitar/habilitar webhooks a qualquer momento sem perder a configuração.

### Passo 10: Testar Seu Webhook

Antes de entrar em produção, teste seu webhook:

<Steps>
  <Step title="Enviar evento de teste">
    Clique em **Testar Webhook** no dashboard

    Gu1 envia um payload de teste:

    ```json theme={null}
    {
      "event": "webhook.test",
      "timestamp": "2025-01-15T10:30:00Z",
      "webhookId": "webhook-uuid",
      "data": {
        "message": "This is a test webhook from Gu1"
      }
    }
    ```
  </Step>

  <Step title="Verificar recebimento">
    Verifique os logs do seu endpoint para confirmar:

    * ✅ Solicitação recebida
    * ✅ Assinatura verificada (se implementado)
    * ✅ Status 200 retornado
  </Step>

  <Step title="Revisar logs">
    No dashboard Gu1, visualize a entrega de teste:

    * Código de status HTTP
    * Tempo de resposta
    * Corpo da resposta
    * Quaisquer erros
  </Step>
</Steps>

## Gerenciando Webhooks

### Visualizar Lista de Webhooks

Vá para **Configurações → Webhooks** para ver todos os webhooks configurados:

**Informações exibidas**:

* Nome e descrição
* Endpoint URL
* Ambiente (sandbox/produção)
* Status (habilitado/desabilitado)
* Inscrições de eventos
* Estatísticas (contagens de sucesso/falha)
* Último timestamp acionado

### Editar Webhook

Clique em um webhook para editar:

* ✏️ Atualizar nome, descrição ou URL
* 🔔 Mudar inscrições de eventos
* 🎯 Modificar filtros
* ⚙️ Ajustar política de tentativas
* 🔄 Adicionar/remover headers personalizados

As mudanças entram em vigor imediatamente.

### Visualizar Logs de Webhook

Clique em **Ver Logs** ou **Histórico** para ver tentativas de entrega:

**Detalhes do log**:

* Timestamp da entrega
* Tipo de evento
* Código de status HTTP
* Tempo de resposta
* Corpo da resposta
* Número da tentativa de repetição
* Mensagens de erro (se falhou)

**Casos de uso**:

* Depurar falhas de entrega
* Monitorar desempenho
* Investigar eventos duplicados
* Verificar dados do evento

### Regenerar Secret

Se seu secret de webhook for comprometido:

1. Clique em **Regenerar Secret**
2. Copie o novo secret imediatamente
3. Atualize sua aplicação com o novo secret
4. O secret antigo para de funcionar imediatamente

<Warning>
  Regenerar o secret invalida o antigo. Atualize sua aplicação antes de regenerar para evitar tempo de inatividade.
</Warning>

### Desabilitar/Habilitar Webhook

Pause temporariamente um webhook sem excluí-lo:

* Clique no botão para **Desabilitar**
* Nenhum evento será enviado enquanto desabilitado
* Toda a configuração é preservada
* Reabilite a qualquer momento para retomar

**Casos de uso**:

* Manutenção no seu endpoint
* Depuração de problemas
* Parar temporariamente o fluxo de eventos

### Excluir Webhook

Remover permanentemente um webhook:

1. Clique em **Excluir** no webhook
2. Confirme a exclusão
3. Webhook é removido permanentemente
4. Logs são retidos por 90 dias

<Warning>
  A exclusão não pode ser desfeita. Considere desabilitar em vez disso se você precisar dele novamente.
</Warning>

## Monitoramento e Estatísticas

Cada webhook exibe métricas principais:

### Taxa de Sucesso

* **Total de Acionamentos**: Total de tentativas de entrega
* **Contagem de Sucessos**: Entregas bem-sucedidas (respostas 2xx)
* **Contagem de Falhas**: Entregas falhadas
* **Taxa de Sucesso**: Porcentagem de entregas bem-sucedidas

### Timestamps

* **Último Acionamento**: Tentativa de entrega mais recente
* **Último Sucesso**: Entrega bem-sucedida mais recente
* **Última Falha**: Entrega falhada mais recente

### Desempenho

* **Tempo Médio de Resposta**: Tempo médio para seu endpoint responder
* **Tempo de Resposta P95**: Tempo de resposta do percentil 95

Use essas métricas para:

* Identificar webhooks problemáticos
* Monitorar saúde do endpoint
* Otimizar processamento de webhook
* Detectar problemas de entrega

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Use Nomes Descritivos">
    Nomeie webhooks claramente para identificar seu propósito:

    ✅ Bom: "KYC de Produção → Integração CRM"

    ❌ Ruim: "Webhook 1"
  </Accordion>

  <Accordion title="Ambientes Separados">
    Crie webhooks diferentes para sandbox e produção:

    * URLs diferentes (staging vs produção)
    * Teste em sandbox primeiro
    * Nunca misture ambientes
  </Accordion>

  <Accordion title="Comece com Eventos Específicos">
    Comece com eventos que você precisa, expanda depois:

    ✅ Início: Inscreva-se em `kyc.validation_approved`

    ✅ Depois: Adicione `kyc.validation_rejected`, `entity.status_changed`
  </Accordion>

  <Accordion title="Use Filtros Sabiamente">
    Adicione filtros para reduzir ruído:

    * Filtre por tipo de entidade se você só se importa com pessoas
    * Filtre por mudanças de status para transições específicas
    * Use filtros personalizados para cenários complexos
  </Accordion>

  <Accordion title="Monitore Regularmente">
    Verifique a saúde do webhook semanalmente:

    * Revise taxas de sucesso
    * Investigue falhas
    * Verifique tempos de resposta
    * Atualize filtros conforme necessário
  </Accordion>

  <Accordion title="Documente Seus Webhooks">
    Mantenha documentação interna:

    * Qual webhook lida com o quê
    * Quais ações ele aciona
    * Quem possui a integração
    * Passos de solução de problemas
  </Accordion>
</AccordionGroup>

## Solução de Problemas

<AccordionGroup>
  <Accordion title="Webhook Não Recebe Eventos">
    **Lista de verificação**:

    * ✅ Webhook está habilitado
    * ✅ Ambiente correto selecionado
    * ✅ Inscrito nos tipos de eventos corretos
    * ✅ Filtros não muito restritivos
    * ✅ URL está correta e acessível
    * ✅ Endpoint retorna status 200

    Verifique os logs de webhook para tentativas de entrega e erros.
  </Accordion>

  <Accordion title="Todas as Entregas Falhando">
    **Causas comuns**:

    * Endpoint está fora do ar ou inacessível
    * Firewall bloqueando solicitações Gu1
    * Endpoint com timeout (>30s)
    * Endpoint retornando status não-2xx
    * Problemas de certificado SSL

    Verifique os logs do seu servidor e logs de entrega de webhook no Gu1.
  </Accordion>

  <Accordion title="Recebendo Muitos Eventos">
    **Soluções**:

    * Adicione filtros para estreitar o escopo
    * Cancele inscrição de tipos de eventos não usados
    * Use filtros de tipo de entidade
    * Adicione filtros de mudança de status

    Revise quais eventos você realmente precisa.
  </Accordion>

  <Accordion title="Eventos Duplicados">
    Este é um comportamento normal devido a tentativas. Sempre implemente idempotência usando IDs de eventos.

    [Saiba sobre lidar com duplicatas →](/pt/webhooks/security)
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Implementar Seu Endpoint" icon="code" href="/pt/webhooks/security">
    Crie um endpoint com verificação de assinatura
  </Card>

  <Card title="Explorar Tipos de Eventos" icon="list" href="/pt/webhooks/events/entity-events">
    Veja todos os eventos disponíveis e payloads
  </Card>

  <Card title="Revisar Guia de Segurança" icon="shield-check" href="/pt/webhooks/security">
    Aprenda sobre verificação de assinatura HMAC
  </Card>

  <Card title="Ver Código de Exemplo" icon="file-code" href="/pt/webhooks/events/kyc-events">
    Veja exemplos de implementação completos
  </Card>
</CardGroup>