Webhooks

Cadastrar o endpoint

Na área Webhooks do dashboard, informe uma URL HTTPS pública, ambiente e eventos. O segredo whsec_ aparece apenas no cadastro. Essa configuração usa a sessão do dashboard, não uma chave Bearer.

Mantenha endpoints separados para sandbox e produção. O botão de teste envia ping.test ao endpoint ativo.

Formato da entrega

A requisição usa POST com JSON, X-MingoPay-Event e X-MingoPay-Signature. O corpo contém id, type, createdAt e data. O objeto data muda conforme o evento; consulte a cobrança quando precisar do estado completo.

X-MingoPay-Event: payment_intent.paid
X-MingoPay-Signature: t=1700000000,v1=<hex-hmac-sha256>

{"id":"<event-id>","type":"payment_intent.paid","createdAt":"<iso-date>","data":{"paymentIntentId":"<payment-id>","amountCents":14990,"currency":"BRL"}}

Validar assinatura

Leia o corpo bruto. Calcule HMAC-SHA256 de timestamp + ponto + corpo com o segredo do endpoint. Compare o digest hexadecimal com v1 em tempo constante e rejeite timestamps fora da sua janela de tolerância.

import { createHmac, timingSafeEqual } from "node:crypto";

function validSignature(rawBody, header, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? "");
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac("sha256", secret).update(match[1] + "." + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}

Repetição e eventos

Responda 2xx após aceitar o evento. Falhas e timeouts são tentados novamente com intervalo crescente, até 10 tentativas; depois podem ir para dead letter. O dashboard mostra as entregas e permite reenviar falhas.

Persista o id do evento e processe cada id uma vez. A API emite payment_intent.pending, paid, failed, cancelled e refunded conforme a mudança de estado. Uma devolução parcial também emite payment_intent.refunded; consulte a cobrança para ler partially_refunded. ping.test testa o endpoint. Eventos de transferência podem ser emitidos pelo worker.