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

# Visão Geral de Webhooks

> Notificações em tempo real para todos os eventos na sua organização Gu1 — com eventos webhook gu1 para integração downstream em tempo real.

## O Que São Webhooks?

Webhooks permitem que você receba notificações HTTP em tempo real quando eventos ocorrem na sua organização Gu1. Em vez de consultar a API repetidamente, Gu1 envia solicitações POST automáticas para o seu endpoint configurado sempre que algo importante acontece.

## Por Que Usar Webhooks?

<CardGroup cols={2}>
  <Card title="Atualizações em Tempo Real" icon="bolt">
    Receba notificações instantâneas conforme os eventos acontecem
  </Card>

  <Card title="Eficiente" icon="gauge-high">
    Não é necessário consultar a API repetidamente
  </Card>

  <Card title="Fluxos de Trabalho Automatizados" icon="robot">
    Acione ações automaticamente com base em eventos
  </Card>

  <Card title="Escalável" icon="chart-line">
    Lide com grandes volumes sem impacto no desempenho
  </Card>
</CardGroup>

## Como Funcionam os Webhooks

```mermaid theme={null}
sequenceDiagram
    participant App as Sua Aplicação
    participant Gu1 as Plataforma Gu1
    participant Endpoint as Seu Endpoint Webhook

    App->>Gu1: Configurar URL do webhook
    Note over Gu1: Evento ocorre<br/>(entidade criada, KYC aprovado, etc.)
    Gu1->>Endpoint: POST /webhooks<br/>com dados do evento
    Endpoint->>Gu1: 200 OK
    Note over Endpoint: Processar evento<br/>assincronamente
```

1. **Configure** um webhook no seu dashboard Gu1
2. **Inscreva-se** em tipos de eventos específicos
3. **Receba** solicitações HTTP POST quando eventos ocorrem
4. **Processe** eventos na sua aplicação

## Tipos de Eventos Disponíveis

Gu1 suporta webhooks para as seguintes categorias:

### Eventos de Entidades

Rastreie mudanças em pessoas, empresas e outras entidades:

* `entity.created` - Nova entidade criada
* `entity.updated` - Dados da entidade atualizados
* `entity.status_changed` - Status da entidade alterado
* `entity.deleted` - Entidade excluída (em breve)

[Saiba mais sobre Eventos de Entidades →](/pt/webhooks/events/entity-events)

### Eventos KYC

Monitore processos de verificação de identidade:

* `kyc.validation_created` - Validação KYC iniciada
* `kyc.validation_in_progress` - Usuário começou verificação
* `kyc.validation_approved` - Verificação aprovada
* `kyc.validation_rejected` - Verificação falhou
* `kyc.validation_abandoned` - Usuário abandonou processo
* `kyc.validation_expired` - Sessão de validação expirou

[Saiba mais sobre Eventos KYC →](/pt/webhooks/events/kyc-events)

### Eventos de Regras

Rastreie execuções de regras de conformidade e negócio:

* `rule.triggered` - Regra correspondeu e executou

[Saiba mais sobre Eventos de Regras →](/pt/webhooks/events/rule-events)

### Eventos de Análise de Risco

Receba notificações quando uma execução de matriz de risco for concluída:

* `risk_analysis_entity_executed` - Matriz de risco executada em pessoa ou empresa
* `risk_analysis_transaction_executed` - Matriz de risco executada em transação

[Saiba mais sobre Eventos de Análise de Risco →](/pt/webhooks/events/risk-analysis-events)

### Eventos de Segurança e IAM

Monitore autenticação, membros, perfis e configurações de segurança para integrações SIEM:

* `security.auth.login_succeeded` / `security.auth.logout` / `security.auth.login_failed`
* `security.member.*` - Convite, criação, remoção, ativação, perfil, senha (admin), equipes, canais e acesso a ambientes (production/sandbox)
* `security.role.*` - CRUD de perfis, atribuição e revogação
* `security.rbac.granular_toggled` - RBAC granular habilitado/desabilitado
* `security.settings.updated` - Sandbox e outras configurações de segurança auditadas

[Saiba mais sobre Eventos de Segurança →](/pt/webhooks/events/security-events)

### Eventos de Transação (Em Breve)

Monitore atividade de transações:

* `transaction.created` - Nova transação registrada
* `transaction.updated` - Transação atualizada (instantâneo completo; inclui mudanças de status)
* `transaction.status_changed` - Apenas transição de status (payload compacto quando o status muda)
* `transaction.flagged` - Transação sinalizada como suspeita

[Saiba mais sobre eventos de transação →](/pt/webhooks/events/transaction-events)

### Eventos de Alerta (Em Breve)

Rastreie investigações e alertas:

* `alert.created` - Novo alerta criado
* `alert.resolved` - Alerta resolvido
* `alert.status_changed` - Status do alerta alterado

## Recursos Principais

### Configuração no Nível da Organização

Webhooks são configurados no **nível da organização**, não por solicitação. Uma configuração se aplica a todos os eventos correspondentes na sua organização.

### Suporte a Ambientes

Crie webhooks separados para diferentes ambientes:

* **Sandbox** - Para testes e desenvolvimento
* **Produção** - Para operações ao vivo

### Filtragem Avançada

Filtre quais eventos acionam webhooks:

* **Tipos de entidades** - Apenas pessoas, apenas empresas, etc.
* **Mudanças de status** - Apenas quando mudar de/para status específicos
* **Filtros personalizados** - Critérios adicionais baseados em dados do evento

### Segurança

* **Assinaturas HMAC SHA-256** - Verifique se as solicitações são do Gu1
* **HTTPS obrigatório** - Todos os webhooks devem usar endpoints seguros
* **Rotação de secrets** - Regenere secrets a qualquer momento

### Confiabilidade

* **Tentativas automáticas** - Solicitações falhadas são repetidas com backoff exponencial
* **Política de tentativas configurável** - Personalize o comportamento de tentativas por webhook
* **Logs de entrega** - Rastreie todas as tentativas de entrega e respostas

### Monitoramento

* **Histórico de execução** - Visualize todas as entregas de webhook
* **Estatísticas** - Taxas de sucesso/falha e tempo
* **Rastreamento de erros** - Mensagens de erro detalhadas para depuração

## Início Rápido

Comece com webhooks em 3 passos:

<Steps>
  <Step title="Configurar Webhook">
    Vá para **Configurações → Webhooks** e crie um novo webhook com sua URL de endpoint.

    [Guia de Configuração →](/pt/webhooks/configuration)
  </Step>

  <Step title="Inscrever-se em Eventos">
    Selecione quais tipos de eventos você deseja receber (por exemplo, `entity.*`, `kyc.*`).
  </Step>

  <Step title="Implementar Endpoint">
    Crie um endpoint HTTPS que recebe solicitações POST e verifica assinaturas.

    [Guia de Segurança →](/pt/webhooks/security)
  </Step>
</Steps>

## Casos de Uso Comuns

<AccordionGroup>
  <Accordion title="Onboarding Automatizado de Clientes">
    **Cenário**: Ativar automaticamente contas de clientes quando o KYC é aprovado.

    **Eventos**: `kyc.validation_approved`

    **Ações**:

    * Atualizar status do cliente no seu banco de dados
    * Enviar email de boas-vindas
    * Habilitar recursos da conta
    * Notificar equipes internas
  </Accordion>

  <Accordion title="Monitoramento de Conformidade em Tempo Real">
    **Cenário**: Rastrear mudanças de status de entidades para relatórios de conformidade.

    **Eventos**: `entity.status_changed`, `rule.triggered`

    **Ações**:

    * Registrar mudanças de status para trilha de auditoria
    * Acionar fluxos de trabalho de conformidade
    * Enviar alertas para equipe de conformidade
    * Atualizar pontuações de risco
  </Accordion>

  <Accordion title="Alertas de Risco de Transação">
    **Cenário**: Ser notificado quando transações de alto risco são detectadas.

    **Eventos**: `transaction.flagged`, `alert.created`

    **Ações**:

    * Notificar equipe de fraude imediatamente
    * Pausar transações relacionadas
    * Solicitar verificação adicional
    * Registrar para investigação
  </Accordion>

  <Accordion title="Integração Multi-Sistema">
    **Cenário**: Manter múltiplos sistemas sincronizados com dados Gu1.

    **Eventos**: Todos os eventos de entidade e KYC

    **Ações**:

    * Atualizar CRM com status de verificação
    * Sincronizar com processador de pagamento
    * Atualizar plataforma de análise
    * Acionar automação de marketing
  </Accordion>
</AccordionGroup>

## Estrutura do Webhook

Todos os webhooks seguem um formato padrão:

```json theme={null}
{
  "event": "entity.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "organizationId": "org-123",
  "payload": {
    // Dados específicos do evento
  }
}
```

**Campos comuns**:

* `event` - Identificador do tipo de evento
* `timestamp` - Quando o evento ocorreu (ISO 8601)
* `organizationId` - Seu ID de organização
* `payload` - Dados específicos do evento (variam por tipo de evento)

## Melhores Práticas

<CardGroup cols={2}>
  <Card title="Verificar Assinaturas" icon="shield-check">
    Sempre verifique assinaturas HMAC para garantir que as solicitações são do Gu1
  </Card>

  <Card title="Responder Rapidamente" icon="gauge-max">
    Retorne status 200 dentro de 30 segundos, processe assincronamente
  </Card>

  <Card title="Lidar com Idempotência" icon="repeat">
    Use IDs de eventos para prevenir processamento duplicado
  </Card>

  <Card title="Monitorar Falhas" icon="chart-line">
    Rastreie falhas de entrega de webhook e investigue problemas
  </Card>
</CardGroup>

## Desempenho e Limites

* **Timeout**: 30 segundos por tentativa de entrega
* **Máximo de Tentativas**: 3 (configurável)
* **Atraso de Tentativa**: 1s, 2s, 4s (backoff exponencial)
* **Tamanho do Payload**: Até 1MB por webhook
* **Limite de Taxa**: Nenhum limite imposto (entrega de melhor esforço)

## Obtendo Ajuda

<CardGroup cols={2}>
  <Card title="Guia de Configuração" icon="gear" href="/pt/webhooks/configuration">
    Instruções passo a passo de configuração
  </Card>

  <Card title="Guia de Segurança" icon="lock" href="/pt/webhooks/security">
    Implementar verificação de assinatura
  </Card>

  <Card title="Referência de Eventos" icon="list" href="/pt/webhooks/events/entity-events">
    Todos os tipos de eventos disponíveis
  </Card>

  <Card title="Solução de Problemas" icon="wrench" href="/pt/webhooks/security">
    Problemas comuns e soluções
  </Card>
</CardGroup>

## Próximos Passos

<Steps>
  <Step title="Ler Guia de Configuração">
    Aprenda como configurar webhooks no seu dashboard

    [Guia de Configuração →](/pt/webhooks/configuration)
  </Step>

  <Step title="Explorar Tipos de Eventos">
    Veja todos os eventos disponíveis e seus payloads

    [Eventos de Entidades →](/pt/webhooks/events/entity-events)

    [Eventos KYC →](/pt/webhooks/events/kyc-events)
  </Step>

  <Step title="Implementar Segurança">
    Adicione verificação de assinatura ao seu endpoint

    [Guia de Segurança →](/pt/webhooks/security)
  </Step>
</Steps>