Webhook

Webhook CashOut (Saques)

Receba notificações sobre solicitações de saque. O webhook é disparado quando um saque é processado com sucesso ou falha.

Eventos

Evento	Descrição
`withdrawal.completed`	Saque realizado com sucesso
`withdrawal.failed`	Falha no processamento do saque

Payload - Saque Concluído

webhook-cashout-completed.json

json

{
  "event": "withdrawal.completed",
  "timestamp": "2025-01-15T15:05:00Z",
  "data": {
    "id": 15,
    "companyId": 1,
    "idempotencyKey": "dc2b11dc8007409dbd421ed9014ac18c",
    "value": 10.00,
    "pixKey": "50651470862",
    "pixKeyType": "CPF",
    "creditorDocument": "11111111111111",
    "description": "Saque via chave custom",
    "currency": "BRL",
    "enTransaction": "Successful",
    "providerEndToEndId": "E48756121202501151505XYZ",
    "providerTid": "wld-00000015",
    "metadata": "{\"origem\":\"api\",\"pedidoId\":123}",
    "createdAt": "2025-01-15T15:00:00Z",
    "completedAt": "2025-01-15T15:05:00Z"
  }
}

Payload - Saque com Falha

webhook-cashout-failed.json

json

{
  "event": "withdrawal.failed",
  "timestamp": "2025-01-15T15:05:00Z",
  "data": {
    "id": 16,
    "companyId": 1,
    "idempotencyKey": "wd_test_failed",
    "value": 5000.00,
    "pixKey": "99999999999",
    "pixKeyType": "CPF",
    "description": "Saque teste",
    "currency": "BRL",
    "enTransaction": "Failed",
    "failReason": "Chave PIX não encontrada no DICT",
    "metadata": null,
    "createdAt": "2025-01-15T15:00:00Z"
  }
}

Headers da Requisição

Parametro	Tipo	Descricao
`Content-Type`	`string`	application/json
`X-Webhook-Signature`	`string`	Assinatura HMAC-SHA256 do payload
`X-Webhook-Timestamp`	`string`	Timestamp da requisição (Unix epoch)
`X-Webhook-Id`	`string`	ID único da notificação (para idempotência)

Exemplo de Handler

webhook-cashout-handler.js

javascript

app.post('/webhook/rayo/cashout', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
 
  // Validar assinatura (ver Webhook PixIn para implementação completa)
  if (!validateWebhookSignature(req.body, signature, timestamp, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  const { event, data } = req.body;
 
  switch (event) {
    case 'withdrawal.completed':
      console.log('Saque concluído:', data.id);
      console.log('EndToEnd:', data.providerEndToEndId);
      // Atualizar status no seu sistema
      break;
 
    case 'withdrawal.failed':
      console.log('Saque falhou:', data.id);
      console.log('Motivo:', data.failReason);
      // Notificar e agendar retry se necessário
      break;
  }
 
  res.status(200).json({ received: true });
});

Campos Principais

Parametro	Tipo	Descricao
`id`	`number`	ID interno do saque
`idempotencyKey`	`string`	Chave de idempotência enviada na criação
`value`	`number`	Valor do saque em reais
`enTransaction`	`string`	Status: Successful ou Failed
`providerEndToEndId`	`string`	EndToEnd ID do PIX (quando sucesso)
`providerTid`	`string`	TID do provedor
`failReason`	`string`	Motivo da falha (quando falhou)
`metadata`	`string`	Metadados enviados na criação do saque

Metadata

O campo metadata que você enviou ao solicitar o saque será retornado exatamente como foi salvo. Se enviou um objeto JSON, ele virá como string JSON.