Skip to main content

​
O que são Webhooks?

Webhooks são requisições HTTP POST enviadas automaticamente para uma URL de sua escolha sempre que eventos específicos ocorrem em nossa plataforma. Isso permite que sua aplicação seja notificada instantaneamente sobre mudanças no status de pagamentos, sem a necessidade de fazer polling constante na API.

​
Como Configurar Webhooks

​
Acessando a Configuração

Para configurar seus webhooks, siga este caminho na plataforma:
  1. Menu Lateral → Desenvolvedor → Webhooks
  2. Clique em “Criar Webhook”
  3. Configure a URL de destino e eventos desejados
Importante: Certifique-se de que sua URL de webhook esteja acessível publicamente e possa receber requisições POST.

​
Configurações Necessárias

  • URL do Endpoint: URL onde você receberá as notificações
  • Eventos: Selecione quais eventos deseja receber
  • Descrição: Nome identificador para o webhook
  • Status: Ativo/Inativo

​
Eventos Disponíveis

Nossa plataforma oferece 5 tipos de eventos de webhook, todos retornando informações completas da charge:

​
1. Charge.Pending (Charge Criada)

Disparado quando uma nova cobrança é criada no sistema. 
{
  "event": "Charge.Pending",
  "charge": {
    "id": "chg_abc123",
    "status": "pending",
    "amount": 10000,
    "currency": "BRL",
    "created_at": "2025-12-15T10:30:00Z",
    // ... outras informações da charge
  }
}
Quando ocorre:
  • Link de pagamento é criado
  • Cobrança é gerada via API
  • Cliente acessa o link mas ainda não iniciou o pagamento

​
2. Charge.Processing

Disparado quando o pagamento está sendo processado. 
{
  "event": "Charge.Processing",
  "charge": {
    "id": "chg_abc123",
    "status": "processing",
    "total": 10000,
    // ... outras informações da charge
  }
}
Quando ocorre:
  • Cliente confirma o pagamento
  • Transação é enviada para processamento
  • Aguardando confirmação da operadora

​
3. Charge.Paid

Disparado quando o pagamento é confirmado como pago. 
{
  "event": "Charge.Paid",
  "charge": {
    "id": "chg_abc123",
    "status": "paid",
    "total": 10000,
    // ... outras informações da charge
  }
}
Quando ocorre:
  • Pagamento é aprovado pela operadora
  • Transação PIX é confirmada
  • Boleto é compensado

​
4. Charge.Received (Valor Disponível para Saque)

Disparado quando o valor da cobrança fica disponível para saque. 
{
  "event": "Charge.Received",
  "charge": {
    "id": "chg_abc123",
    "status": "received",
    "total": 10000,
    // ... outras informações da charge
  }
}
Quando ocorre:
  • Período de análise de risco finalizado
  • Valor liberado para saque
  • Disponível no saldo da conta

​
5. Charge.Expired

Disparado quando uma cobrança expira sem ser paga. 
{
  "event": "Charge.Expired",
  "charge": {
    "id": "chg_abc123",
    "status": "expired",
    "total": 10000,
    // ... outras informações da charge
  }
}
Quando ocorre:
  • Data de vencimento é ultrapassada
  • Link de pagamento expira
  • Cobrança é cancelada automaticamente

​
Implementação do Endpoint

​
Estrutura Básica

Seu endpoint deve:
  1. Aceitar POST requests
  2. Responder com status 200 para confirmar recebimento
  3. Processar rapidamente (timeout de 30 segundos)
  4. Validar a assinatura para segurança

​
Exemplo de Implementação

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const payload = req.body
  const event = JSON.parse(payload);
  
  switch(event.event) {
    case 'Charge.Pending':
      // Lógica para charge criada
      break;
    case 'Charge.Processing':
      // Lógica para charge em processamento
      break;
    case 'Charge.Paid':
      // Lógica para charge paga
      break;
    case 'Charge.Received':
      // Lógica para valor disponível
      break;
    case 'Charge.Expired':
      // Lógica para charge expirada
      break;
  }
  
  res.status(200).send('OK');
});

​
Tentativas de Entrega

​
Política de Retry

  • Tentativas: Até 5 tentativas
  • Intervalos: 1min, 5min, 15min, 1h, 6h
  • Timeout: 30 segundos por tentativa
  • Status de sucesso: 200-299

​
Logs de Webhook

Na plataforma você pode acompanhar:
  • ✅ Entregas bem-sucedidas
  • ❌ Falhas de entrega
  • 🔄 Tentativas de retry
  • 📊 Histórico completo

​
Testando Webhooks

​
No Modo Teste

Durante o desenvolvimento, use o modo teste para:
  1. Simular pagamentos e receber webhooks
  2. Validar sua implementação sem transações reais
  3. Testar todos os eventos de forma controlada
  4. Debug com logs detalhados

​
Ferramentas Recomendadas

  • ngrok: Para expor localhost publicamente
  • Postman: Para testar endpoints
  • curl: Para testes rápidos via terminal
Dica: Use ferramentas como ngrok durante o desenvolvimento para testar webhooks localmente antes de fazer deploy.

​
Perguntas Frequentes

Sim, você pode configurar múltiplos webhooks com URLs diferentes e eventos específicos para cada um.
O sistema tentará reenviar o webhook seguindo nossa política de retry. Após 5 tentativas sem sucesso, o webhook será marcado como falhou.
Use ferramentas como ngrok para expor seu ambiente local ou configure um servidor de testes acessível publicamente.
Sim, na configuração do webhook você pode selecionar especificamente quais eventos deseja receber.

​
Suporte

Se você encontrar problemas com webhooks ou precisar de ajuda na implementação:
  • Email: [email protected]
  • Chat: Disponível no painel de controle
  • Documentação: Consulte outros guias técnicos
Importante: Sempre teste seus webhooks extensivamente no ambiente de teste antes de ativar em produção.