Skip to main content

Cadastrar um endpoint

Informe um domínio HTTPS público e selecione os eventos necessários. O segredo aparece uma vez na criação. Cadastrar webhook.

{
  "url": "https://seu-dominio.com/webhook",
  "events": [
    "payment.paid",
    "withdrawal.completed"
  ]
}

Eventos disponíveis

EventoQuando é usado
payment.createdCobrança criada
payment.paidConfirmação de pagamento
payment.failedOperação não concluída
payment.refundedDevolução concluída
pix.receivedConfirmação de pagamento
pix.sentResultado de um envio
transaction.paidConfirmação de pagamento
withdrawal.completedResultado de um envio
withdrawal.failedOperação não concluída

Validar a assinatura

Calcule HMAC-SHA256 sobre os bytes originais do corpo, usando o segredo do endpoint. Compare com o valor do header X-Webhook-Signature, após remover sha256=.

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

const expected = createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody).digest('hex');
const supplied = signature.replace(/^sha256=/, '');
const valid = supplied.length === expected.length &&
  timingSafeEqual(Buffer.from(supplied), Buffer.from(expected));

Formato do evento

{
  "id": "pay_exemplo:payment.paid",
  "event": "payment.paid",
  "data": {
    "id": "pay_exemplo",
    "amount": 5,
    "feeAmount": 0.1,
    "netAmount": 4.9,
    "status": "COMPLETED",
    "currency": "BRL"
  },
  "createdAt": "2026-11-10T15:00:00.000Z"
}

Confirmação e retentativas

Responda HTTP 2xx após validar e registrar o evento. Deduplique pelo id. As entregas têm timeout de 8 segundos, até cinco tentativas e intervalos crescentes de 30, 60, 120 e 240 segundos. O envio automático depende da fila e do transporte de webhooks ativos no ambiente.

Pesquisar documentação