Rayo - Gateway PIX

Webhooks

Receba notificacoes em tempo real sobre eventos de pagamento.

Visao Geral

Webhooks permitem que sua aplicacao receba notificacoes automaticas quando eventos importantes ocorrem, como confirmacao de pagamento ou falha em saque. Em vez de consultar a API repetidamente (polling), voce recebe uma requisicao HTTP POST diretamente no seu servidor.

Configuracao

Para configurar webhooks:

Acesse o painel em https://rayopay.com.br/login-company
Navegue ate Configuracoes → Webhooks
Adicione a URL do seu endpoint
Selecione os eventos que deseja receber
Copie o Webhook Secret para validar as requisicoes

Eventos Disponiveis

Evento	Descricao
`transaction.paid`	Pagamento PIX confirmado
`transaction.expired`	QR Code PIX expirado
`transaction.cancelled`	Transacao cancelada
`withdrawal.completed`	Saque realizado com sucesso
`withdrawal.failed`	Falha no processamento do saque

Formato do Payload

Todas as notificacoes webhook sao enviadas via POST com o seguinte formato:

webhook-payload.json

json

{
  "event": "transaction.paid",
  "timestamp": "2024-01-15T15:10:00Z",
  "data": {
    "id": "f2d96218-6635-4839-81d7-9f2d5aaf4f14",
    "status": "PAID",
    "paymentMethod": "PIX",
    "amount": 500,
    "externalId": "pedido-123",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "cpfCnpj": "12345678900"
    },
    "pix": {
      "paidAt": "2024-01-15T15:10:00Z",
      "endToEndId": "E12345678202401151510ABCDEF"
    }
  }
}

Headers da Requisicao

Parametro	Tipo	Descricao
`Content-Type`	`string`	application/json
`X-Webhook-Signature`	`string`	Assinatura HMAC-SHA256 do payload
`X-Webhook-Timestamp`	`string`	Timestamp da requisicao (Unix epoch)
`X-Webhook-Id`	`string`	ID unico da notificacao (para idempotencia)

Validacao de Assinatura

Sempre valide a assinatura do webhook para garantir que a requisicao veio da Rayo:

webhook-handler.js

javascript

import crypto from 'crypto';
 
function validateWebhookSignature(payload, signature, timestamp, secret) {
  // Construir a string para assinatura
  const signaturePayload = `${timestamp}.${JSON.stringify(payload)}`;
  
  // Calcular HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');
  
  // Comparar de forma segura
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
// No seu endpoint
app.post('/webhook/rayo', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  if (!validateWebhookSignature(req.body, signature, timestamp, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Processar o webhook
  const { event, data } = req.body;
  
  switch (event) {
    case 'transaction.paid':
      // Liberar produto/serviço
      console.log('Pagamento confirmado:', data.id);
      break;
    case 'withdrawal.completed':
      // Atualizar status do saque
      console.log('Saque concluído:', data.id);
      break;
  }
  
  // Sempre retornar 200 para confirmar recebimento
  res.status(200).json({ received: true });
});

Boas Praticas

1. Responda rapidamente

Retorne status 200 imediatamente e processe o webhook de forma assincrona. Webhooks que demoram mais de 30 segundos serao considerados falhos.

2. Implemente idempotencia

Use o header X-Webhook-Id para evitar processar o mesmo evento duas vezes. Armazene os IDs ja processados.

3. Valide a assinatura

Sempre valide o header X-Webhook-Signature antes de processar qualquer webhook para evitar requisicoes maliciosas.

4. Use HTTPS

Seu endpoint deve usar HTTPS. Requisicoes para endpoints HTTP serao rejeitadas.

Retentativas

Se seu endpoint retornar um codigo de erro ou nao responder, tentaremos novamente:

Tentativa	Intervalo
1a tentativa	Imediato
2a tentativa	5 minutos
3a tentativa	30 minutos
4a tentativa	2 horas
5a tentativa	24 horas

Teste seus Webhooks

Use o painel para enviar webhooks de teste e validar sua implementacao antes de processar eventos reais.