Skip to main content

​
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
  • ✅ (Opcional) Um secret de webhook para verificação de assinatura
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

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

​
Passo 2: Informações Básicas

1

Nomear seu webhook

Digite um nome descritivo para identificar este webhookExemplos:
  • “Webhook KYC de Produção”
  • “Eventos de Entidade Sandbox”
  • “Monitoramento de Conformidade”
2

Adicionar descrição (opcional)

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

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:
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:
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
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
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:
  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)
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: Salvar Secret do Webhook

Após criar o webhook, Gu1 gera automaticamente um secret:
1

Copiar o secret

IMPORTANTE: Copie e salve este secret imediatamente. Você não poderá vê-lo novamente.O secret se parece com: whsec_abc123def456...
2

Armazenar com segurança

Salve o secret nas suas variáveis de ambiente ou gerenciador de secrets:
# arquivo .env
GU1_WEBHOOK_SECRET=whsec_abc123def456...
3

Usar para verificação

Use este secret para verificar assinaturas de webhook no seu endpoint.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:
1

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"
  }
}
2

Verificar recebimento

Verifique os logs do seu endpoint para confirmar:
  • ✅ Solicitação recebida
  • ✅ Assinatura verificada (se implementado)
  • ✅ Status 200 retornado
3

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:
  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
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:
  1. Clique em Excluir no webhook
  2. Confirme a exclusão
  3. Webhook é removido permanentemente
  4. 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

Nomeie webhooks claramente para identificar seu propósito:✅ Bom: “KYC de Produção → Integração CRM”❌ Ruim: “Webhook 1”
Crie webhooks diferentes para sandbox e produção:
  • URLs diferentes (staging vs produção)
  • Teste em sandbox primeiro
  • Nunca misture ambientes
Comece com eventos que você precisa, expanda depois:✅ Início: Inscreva-se em kyc.validation_approved✅ Depois: Adicione kyc.validation_rejected, entity.status_changed
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
Verifique a saúde do webhook semanalmente:
  • Revise taxas de sucesso
  • Investigue falhas
  • Verifique tempos de resposta
  • Atualize filtros conforme necessário
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

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