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 espera progressiva entre elas.

Payload do Webhook

Exemplo de payloadjson

{
  "event": "transaction.completed",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "externalId": "txn_abc123",
    "amount": 99.90,
    "netAmount": 99.40,
    "status": "COMPLETED",
    "payerName": "João Silva",
    "completedAt": "2024-01-15T14:05:30.000Z"
  },
  "timestamp": "2024-01-15T14:05:31.000Z"
}

Tipos de Eventos

Evento	Descrição
`transaction.created`	Transação criada
`transaction.completed`	Transação confirmada
`transaction.failed`	Transação falhou

Respondendo ao Webhook

Seu endpoint deve retornar um status HTTP entre 200–299 em até 10 segundos. Em caso de falha, faremos até 3 tentativas com espera progressiva.

server.jsjavascript

// Exemplo em Node.js / Express
app.post('/webhook/magnus', (req, res) => {
  const { event, data } = req.body
  
  switch (event) {
    case 'transaction.completed':
      // Processar pagamento confirmado
      console.log('Concluída:', data.id, 'R$', data.amount)
      break
  }
  
  res.status(200).json({ received: true })
})

🔐 Segurança

Todos os webhooks incluem o header X-mc-Signature com uma assinatura HMAC-SHA256 do corpo bruto. Use o secret próprio do webhook; se ele não estiver definido, a API Key vinculada é usada como fallback.

verify-signature.jsjavascript

const crypto = require('crypto')

const isValidSignature = (rawBody, signature, webhookSecret) => {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}