Skip to main content

​
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?

Atualizações em Tempo Real

Receba notificações instantâneas conforme os eventos acontecem

Eficiente

Não é necessário consultar a API repetidamente

Fluxos de Trabalho Automatizados

Acione ações automaticamente com base em eventos

Escalável

Lide com grandes volumes sem impacto no desempenho

​
Como Funcionam os Webhooks

  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 →

​
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 →

​
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 →

​
Eventos de Transação (Em Breve)

Monitore atividade de transações:
  • transaction.created - Nova transação registrada
  • transaction.updated - Transação atualizada
  • transaction.flagged - Transação sinalizada como suspeita

​
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:
1

Configurar Webhook

Vá para Configurações → Webhooks e crie um novo webhook com sua URL de endpoint.Guia de Configuração →
2

Inscrever-se em Eventos

Selecione quais tipos de eventos você deseja receber (por exemplo, entity.*, kyc.*).
3

Implementar Endpoint

Crie um endpoint HTTPS que recebe solicitações POST e verifica assinaturas.Guia de Segurança →

​
Casos de Uso Comuns

Cenário: Ativar automaticamente contas de clientes quando o KYC é aprovado.Eventos: kyc.validation_approvedAções:
  • Atualizar status do cliente no seu banco de dados
  • Enviar email de boas-vindas
  • Habilitar recursos da conta
  • Notificar equipes internas
Cenário: Rastrear mudanças de status de entidades para relatórios de conformidade.Eventos: entity.status_changed, rule.triggeredAçõ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
Cenário: Ser notificado quando transações de alto risco são detectadas.Eventos: transaction.flagged, alert.createdAções:
  • Notificar equipe de fraude imediatamente
  • Pausar transações relacionadas
  • Solicitar verificação adicional
  • Registrar para investigação
Cenário: Manter múltiplos sistemas sincronizados com dados Gu1.Eventos: Todos os eventos de entidade e KYCAções:
  • Atualizar CRM com status de verificação
  • Sincronizar com processador de pagamento
  • Atualizar plataforma de análise
  • Acionar automação de marketing

​
Estrutura do Webhook

Todos os webhooks seguem um formato padrão: 
{
  "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

Verificar Assinaturas

Sempre verifique assinaturas HMAC para garantir que as solicitações são do Gu1

Responder Rapidamente

Retorne status 200 dentro de 30 segundos, processe assincronamente

Lidar com Idempotência

Use IDs de eventos para prevenir processamento duplicado

Monitorar Falhas

Rastreie falhas de entrega de webhook e investigue problemas

​
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

Guia de Configuração

Instruções passo a passo de configuração

Guia de Segurança

Implementar verificação de assinatura

Referência de Eventos

Todos os tipos de eventos disponíveis

Solução de Problemas

Problemas comuns e soluções

​
Próximos Passos

1

Ler Guia de Configuração

Aprenda como configurar webhooks no seu dashboardGuia de Configuração →
2

Explorar Tipos de Eventos

Veja todos os eventos disponíveis e seus payloadsEventos de Entidades →Eventos KYC →
3

Implementar Segurança

Adicione verificação de assinatura ao seu endpointGuia de Segurança →