HOOK

Webhooks

Receba notificações via HTTP POST quando eventos ocorrerem na sua conta.

Como funciona

Configure uma URL de webhook nas suas credenciais ou ao criar um pagamento. Quando o status mudar, enviaremos um POST para essa URL com os dados do evento.

Em caso de falha, fazemos até 3 tentativas com intervalos de 5s, 30s e 2min.

Payload do Webhook

Exemplo de payloadjson

{
  "event": "payment.completed",
  "data": {
    "id": "pag_abc123xyz",
    "amount": 99.90,
    "status": "COMPLETED",
    "externalId": "pedido_12345",
    "paidAt": "2024-01-15T14:05:30.000Z"
  },
  "timestamp": "2024-01-15T14:05:31.000Z"
}

Tipos de Eventos

Evento	Descrição
`payment.completed`	Pagamento confirmado
`payment.expired`	QR Code expirou
`withdrawal.completed`	Saque concluído
`withdrawal.failed`	Saque falhou

Respondendo ao Webhook

Seu endpoint deve retornar status 200 em até 5 segundos. Em caso de falha, faremos até 3 tentativas com intervalo de 30 segundos.

server.jsjavascript

// Exemplo em Node.js / Express
app.post('/webhook/vye', (req, res) => {
  const { event, data } = req.body
  
  switch (event) {
    case 'payment.completed':
      // Processar pagamento confirmado (data.id)
      break
    case 'withdrawal.completed':
      // Processar saque concluído (data.id)
      break
  }
  
  res.status(200).json({ received: true })
})

🔐 Segurança

Todos os webhooks incluem o header X-Vye-Signature com uma assinatura HMAC-SHA256 do payload usando seu API Key como secret.

verify-signature.jsjavascript

const crypto = require('crypto')

const isValidSignature = (payload, signature, apiKey) => {
  const expected = crypto
    .createHmac('sha256', apiKey)
    .update(JSON.stringify(payload))
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}