Integração
Webhooks
Receba avisos no seu servidor quando um pagamento, reembolso, saque ou infração muda. Valide a assinatura de cada aviso.
Como funciona
- Cadastre a URL HTTPS do seu servidor no painel, em Integração > Webhooks.
- Guarde o segredo de assinatura (começa com
whsec_). Ele aparece uma única vez. - A cada mudança, enviamos um
POSTcom o evento em JSON para a sua URL. - Seu servidor valida a assinatura, guarda o evento e responde
2xxem até 10 segundos.
Eventos
| Evento | Quando acontece |
|---|---|
payment.paid | O pagamento foi confirmado. Libere o pedido. |
payment.expired | O prazo do Pix acabou sem pagamento. |
payment.failed | Não foi possível criar a cobrança Pix. O motivo vem em failure_code. |
refund.requested | Você pediu um reembolso. |
refund.approved | O reembolso foi aprovado e vai ser pago. |
refund.completed | O valor foi devolvido ao cliente. |
refund.rejected | O reembolso foi recusado. O motivo vem em decision_reason. |
refund.failed | O envio do reembolso falhou. O valor voltou ao seu saldo. |
withdrawal.requested | Você pediu um saque. |
withdrawal.approved | O saque foi aprovado e vai ser pago. |
withdrawal.paid | O saque foi pago na sua conta. |
withdrawal.rejected | O saque foi recusado. O motivo vem em reason. |
withdrawal.failed | O envio do saque falhou. O valor voltou ao seu saldo. |
infraction.opened | Um cliente abriu uma contestação. O valor ficou retido. |
infraction.updated | A contestação mudou de status. |
Formato
Todo evento tem o mesmo formato. Em data vem o objeto no momento da mudança. created_at é o momento da mudança, em UTC, no formato RFC 3339.
{
"id": "7d9e6c52-3f1a-4b8e-9a0d-2c4f6e8a1b3c",
"type": "payment.paid",
"created_at": "2026-11-22T15:04:13.284512Z",
"data": {
"id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e",
"status": "paid",
"amount_cents": 15000,
"fee_cents": 1050,
"net_cents": 13950,
"external_id": "pedido-1234",
"metadata": {
"order_id": "1234"
},
"paid_at": "2026-11-22T15:04:12Z",
"paid_late": false,
"expires_at": "2026-11-22T15:30:00Z",
"created_at": "2026-11-22T15:00:00Z",
"payer": {
"name": "Maria Silva",
"document": "12345678909",
"document_type": "cpf"
}
}
}Os eventos payment.* trazem em data.payer os dados completos de quem paga (nome, e-mail quando existir, CPF ou CNPJ). Só a sua conta recebe esses dados: proteja-os como em Criar pagamento, sem gravá-los em logs, conforme a LGPD.
Cabeçalhos de cada envio:
| Cabeçalho | O que é |
|---|---|
Webhook-Id | O id do evento. É o mesmo em todos os reenvios. |
Webhook-Timestamp | Horário deste envio, em segundos Unix. |
Webhook-Signature | A assinatura: v1= seguido de 64 caracteres hexadecimais. |
Content-Type | application/json |
Como validar a assinatura
- Leia o corpo cru da requisição, antes de qualquer conversão de JSON.
- Monte o texto
Webhook-Id+.+Webhook-Timestamp+.+ corpo cru. - Calcule o HMAC-SHA256 desse texto. A chave é o segredo inteiro, com o prefixo
whsec_. - Escreva o resultado em hexadecimal minúsculo e coloque
v1=na frente. - Compare com
Webhook-Signatureusando comparação de tempo constante. - Recuse se o
Webhook-Timestampestiver a mais de 5 minutos do seu relógio.
Se qualquer passo falhar, responda 400 e não use o conteúdo.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.PAYMENTS_WEBHOOK_SECRET; // whsec_...
app.post('/webhooks/pagamentos', express.raw({ type: 'application/json' }), (req, res) => {
const id = req.get('Webhook-Id') ?? '';
const timestamp = req.get('Webhook-Timestamp') ?? '';
const signature = req.get('Webhook-Signature') ?? '';
if (!id || !/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.sendStatus(400);
}
const expected = 'v1=' + crypto.createHmac('sha256', SECRET)
.update(`${id}.${timestamp}.`).update(req.body).digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(400);
const event = JSON.parse(req.body);
// Guarde o evento numa fila e processe depois. Ignore se event.id já foi processado.
res.sendStatus(200);
});<?php
$secret = getenv('PAYMENTS_WEBHOOK_SECRET'); // whsec_...
$id = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$timestamp = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
if ($id === '' || !ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(400);
exit;
}
$expected = 'v1=' . hash_hmac('sha256', $id . '.' . $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
// Guarde o evento numa fila e processe depois. Ignore se $event['id'] já foi processado.
http_response_code(200);import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["PAYMENTS_WEBHOOK_SECRET"].encode() # whsec_...
@app.post("/webhooks/pagamentos")
def webhook():
event_id = request.headers.get("Webhook-Id", "")
timestamp = request.headers.get("Webhook-Timestamp", "")
signature = request.headers.get("Webhook-Signature", "")
if not event_id or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
abort(400)
signed = f"{event_id}.{timestamp}.".encode() + request.get_data()
expected = "v1=" + hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature):
abort(400)
event = request.get_json()
# Guarde o evento numa fila e processe depois. Ignore se event["id"] já foi processado.
return "", 200# Confira uma assinatura na linha de comando (útil em testes).
printf '%s.%s.%s' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" "$BODY" \
| openssl dgst -sha256 -hmac "$PAYMENTS_WEBHOOK_SECRET" -hexReenvios
- Um envio dá certo quando o seu servidor responde
2xxem até 10 segundos. Redirecionamentos contam como falha. - Se falhar, reenviamos o mesmo evento, com o mesmo
id. A espera dobra a cada tentativa: 30 segundos, 1 minuto, 2 minutos, e assim por diante, até 6 horas entre tentativas. - São até 12 tentativas, por cerca de 26 horas. Depois disso o evento fica marcado como não entregue no painel.
- Os eventos podem chegar fora de ordem. Use o
statusdedatae o horáriocreated_at.
Idempotência por event.id
O mesmo evento pode chegar mais de uma vez. Guarde o id de cada evento processado e ignore os repetidos. Faça isso na mesma transação em que você atualiza o pedido.
Boas práticas
- Responda
2xxrápido e processe numa fila. Não faça chamadas lentas antes de responder. - Antes de liberar um pedido ou mexer em dinheiro, confira o pagamento com Buscar um pagamento.
- Guarde o segredo numa variável de ambiente, como a chave de API.