Configuração de Webhook

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.

Para desenvolvimento local, use ferramentas como ngrok para criar uma URL pública que faz túnel para seu servidor local.

Configuração Passo a Passo

Passo 1: Navegar para Configurações de Webhooks

Faça login no seu dashboard Gu1 em app.gu1.ai
Vá para Configurações → Webhooks
Clique em Adicionar Webhook ou Criar Webhook

Passo 2: Informações Básicas

Nomear seu webhook

Digite um nome descritivo para identificar este webhookExemplos:

“Webhook KYC de Produção”
“Eventos de Entidade Sandbox”
“Monitoramento de Conformidade”

Adicionar descrição (opcional)

Adicione notas sobre para que este webhook é usadoExemplo: “Envia eventos de aprovação de KYC para nosso sistema CRM”

Inserir URL do webhook

Forneça a URL do endpoint HTTPS que receberá solicitações POSTRequisitos:

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

Passo 3: Selecionar Ambiente

Escolha a qual ambiente este webhook se aplica:

Sandbox
Produção

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

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

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

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

Passo 5: Configurar Filtros (Opcional)

Adicione filtros para receber apenas eventos relevantes:

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

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

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

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

Personalize como Gu1 lida com entregas de webhook falhadas:

{
  "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:

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

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

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:

{
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-key",
  "X-Custom-Header": "custom-value"
}

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

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

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

Armazenar com segurança

Salve o secret nas suas variáveis de ambiente ou gerenciador de secrets:

# arquivo .env
GU1_WEBHOOK_SECRET=whsec_abc123def456...

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 →

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

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:

Enviar evento de teste

Clique em Testar Webhook no dashboardGu1 envia um payload de teste:

{
  "event": "webhook.test",
  "timestamp": "2025-01-15T10:30:00Z",
  "webhookId": "webhook-uuid",
  "data": {
    "message": "This is a test webhook from Gu1"
  }
}

Verificar recebimento

Verifique os logs do seu endpoint para confirmar:

✅ Solicitação recebida
✅ Assinatura verificada (se implementado)
✅ Status 200 retornado

Revisar logs

No dashboard Gu1, visualize a entrega de teste:

Código de status HTTP
Tempo de resposta
Corpo da resposta
Quaisquer erros

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:

Clique em Regenerar Secret
Copie o novo secret imediatamente
Atualize sua aplicação com o novo secret
O secret antigo para de funcionar imediatamente

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

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:

Clique em Excluir no webhook
Confirme a exclusão
Webhook é removido permanentemente
Logs são retidos por 90 dias

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

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

Use Nomes Descritivos

Nomeie webhooks claramente para identificar seu propósito:✅ Bom: “KYC de Produção → Integração CRM”❌ Ruim: “Webhook 1”

Ambientes Separados

Crie webhooks diferentes para sandbox e produção:

URLs diferentes (staging vs produção)
Teste em sandbox primeiro
Nunca misture ambientes

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

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

Monitore Regularmente

Verifique a saúde do webhook semanalmente:

Revise taxas de sucesso
Investigue falhas
Verifique tempos de resposta
Atualize filtros conforme necessário

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

Solução de Problemas

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.

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.

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.

Eventos Duplicados

Este é um comportamento normal devido a tentativas. Sempre implemente idempotência usando IDs de eventos.Saiba sobre lidar com duplicatas →

Próximos Passos

Implementar Seu Endpoint

Crie um endpoint com verificação de assinatura

Explorar Tipos de Eventos

Veja todos os eventos disponíveis e payloads

Revisar Guia de Segurança

Aprenda sobre verificação de assinatura HMAC

Ver Código de Exemplo

Veja exemplos de implementação completos

​Visão Geral

​Pré-requisitos

​Configuração Passo a Passo

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

​Passo 2: Informações Básicas

​Passo 3: Selecionar Ambiente

​Passo 4: Inscrever-se em Eventos

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

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

​Passo 5: Configurar Filtros (Opcional)

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

​Passo 7: Adicionar Headers Personalizados (Opcional)

​Passo 8: Copiar o Secret Gerado

​Passo 9: Habilitar Webhook

​Passo 10: Testar Seu Webhook

​Gerenciando Webhooks

​Visualizar Lista de Webhooks

​Editar Webhook

​Visualizar Logs de Webhook

​Regenerar Secret

​Desabilitar/Habilitar Webhook

​Excluir Webhook

​Monitoramento e Estatísticas

​Taxa de Sucesso

​Timestamps

​Desempenho

​Melhores Práticas

​Solução de Problemas

​Próximos Passos

Implementar Seu Endpoint

Explorar Tipos de Eventos

Revisar Guia de Segurança

Ver Código de Exemplo

Visão Geral

Pré-requisitos

Configuração Passo a Passo

Passo 1: Navegar para Configurações de Webhooks

Passo 2: Informações Básicas

Passo 3: Selecionar Ambiente

Passo 4: Inscrever-se em Eventos

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

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

Passo 5: Configurar Filtros (Opcional)

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

Passo 7: Adicionar Headers Personalizados (Opcional)

Passo 8: Copiar o Secret Gerado

Passo 9: Habilitar Webhook

Passo 10: Testar Seu Webhook

Gerenciando Webhooks

Visualizar Lista de Webhooks

Editar Webhook

Visualizar Logs de Webhook

Regenerar Secret

Desabilitar/Habilitar Webhook

Excluir Webhook

Monitoramento e Estatísticas

Taxa de Sucesso

Timestamps

Desempenho

Melhores Práticas

Solução de Problemas

Próximos Passos