Skip to main content
O sistema de webhooks permite que você receba notificações em tempo real sobre mudanças no status das transações.

​
Visão Geral

Os webhooks são endpoints HTTP POST configurados no seu sistema para receber notificações automáticas da RelaxPay quando ocorrem eventos importantes.

Pagamentos

Notificações de pagamentos recebidos e estornos

Transferências

Alertas de transferências realizadas ou falhas

Conformidade

Informações sobre validações e verificações

Segurança

Eventos relacionados à segurança da conta

​
Configuração Rápida

1

Crie um endpoint

Adicione um endpoint em seu sistema para receber requisições POST
// Exemplo em Node.js (Express)
app.post('/webhooks/relaxpay', express.json(), (req, res) => {
  // Processar webhook
  res.status(200).send('OK');
});
2

Registre o webhook

Configure a URL do seu endpoint nas suas integrações com a RelaxPay
Acesse Configurações > Webhooks > Adicionar Novo
3

Implemente a validação

​
Eventos Disponíveis

​
payment.received
success
Pagamento recebido com sucesso
​
payment.refunded
warning
Pagamento estornado
​
payment.expired
error
QR Code expirado sem pagamento
​
transfer.completed
success
Transferência concluída com sucesso
​
transfer.failed
error
Transferência falhou
​
transfer.returned
warning
Devolução recebida

​
Formato dos Payloads

​
idTransaction
string
required
ID único da transação
​
typeTransaction
string
required
Tipo da transação (“PIX”)
​
statusTransaction
string
required
Status atual (“PAID_OUT”, “CHARGEBACK”)
​
value
number
required
Valor do pagamento
​
payerName
string
Nome do pagador
​
payerTaxId
string
CPF/CNPJ do pagador
​
paymentDate
string
Data e hora do pagamento (dd/MM/yyyy HH:mm:ss)

​
Validação de Assinaturas

1

Extraia o cabeçalho

Obtenha o cabeçalho X-Signature da requisição
2

Calcule o HMAC

Gere o HMAC-SHA256 do corpo da requisição usando seu Client Secret
3

Compare os valores

Verifique se a assinatura calculada corresponde ao cabeçalho recebido

​
Boas Práticas

Idempotência: Processe eventos de forma idempotente para evitar duplicações
Respostas Rápidas: Responda em até 5 segundos com status 200 para confirmar recebimento
Processamento Assíncrono: Trabalhos pesados devem ser executados após a resposta
Logs: Mantenha registros detalhados de todos os webhooks recebidos
Retry: Implemente lógica de retentativa para falhas temporárias
Seu endpoint de webhook deve responder em até 5 segundos com código 200 para confirmar o recebimento. Processos demorados devem ser executados de forma assíncrona.

​
Solução de Problemas

  • Verifique se a URL está acessível publicamente
  • Confirme que não há firewalls bloqueando a conexão
  • Verifique se a URL foi configurada corretamente no dashboard
  • Verifique se está usando o Client Secret correto
  • Confirme que o payload não está sendo modificado
  • Verifique se está usando o algoritmo HMAC-SHA256
  • Otimize o processamento do seu endpoint
  • Separe o processamento da resposta
  • Armazene o evento e processe-o assincronamente