Webhooks

O Magnum entrega eventos do banco ao seu servidor por uma fila persistente. No sandbox, esses eventos nunca confirmam um pagamento real.

Cadastrar um destino

POST /v1/webhook-endpoints exige webhooks:write.

{ "url": "https://loja.example/hooks/magnum" }

A resposta inclui id, url e signingSecret, exibido uma única vez. URLs precisam usar HTTPS público na porta 443. IPs literais, credenciais, fragmentos e destinos privados são rejeitados. O worker resolve e valida DNS antes de cada tentativa e fixa o IP da conexão; não segue redirecionamentos.

Validar a assinatura

O cabeçalho magnum-signature tem t=TIMESTAMP,v1=HEX. Calcule HMAC-SHA256 de TIMESTAMP + "." + corpoBruto usando o segredo. Compare em tempo constante, aceite no máximo cinco minutos de diferença e deduplique id no seu banco.

import { createHmac, timingSafeEqual } from 'node:crypto';
const expected = createHmac('sha256', signingSecret).update(`${timestamp}.${rawBody}`).digest();
const supplied = Buffer.from(signatureHex, 'hex');
const valid = supplied.length === expected.length && timingSafeEqual(supplied, expected);

Valide formato e prazo antes da comparação. Não transforme o JSON e serialize de novo para verificar: use o corpo original.

Entrega e repetição

Cada evento tem ID estável, tipo, createdAt, livemode e data. O worker usa lease e bloqueio de linha. Considera apenas 2xx como sucesso; tenta até oito vezes com espera exponencial limitada a uma hora. Timeout de uma tentativa: oito segundos. Entrega é pelo menos uma vez.

Consulte GET /v1/webhook-deliveries. Desative destinos com DELETE /v1/webhook-endpoints/:id. O evento sandbox disponível é sandbox.payment.completed. Sua aplicação deve conferir também livemode antes de qualquer ação financeira.