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
| Evento | Quando é usado |
|---|---|
payment.created | Cobrança criada |
payment.paid | Confirmação de pagamento |
payment.failed | Operação não concluída |
payment.refunded | Devolução concluída |
pix.received | Confirmação de pagamento |
pix.sent | Resultado de um envio |
transaction.paid | Confirmação de pagamento |
withdrawal.completed | Resultado de um envio |
withdrawal.failed | Operaçã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.