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

  1. Cadastre a URL HTTPS do seu servidor no painel, em Integração > Webhooks.
  2. Guarde o segredo de assinatura (começa com whsec_). Ele aparece uma única vez.
  3. A cada mudança, enviamos um POST com o evento em JSON para a sua URL.
  4. Seu servidor valida a assinatura, guarda o evento e responde 2xx em até 10 segundos.

Eventos

EventoQuando acontece
payment.paidO pagamento foi confirmado. Libere o pedido.
payment.expiredO prazo do Pix acabou sem pagamento.
payment.failedNão foi possível criar a cobrança Pix. O motivo vem em failure_code.
refund.requestedVocê pediu um reembolso.
refund.approvedO reembolso foi aprovado e vai ser pago.
refund.completedO valor foi devolvido ao cliente.
refund.rejectedO reembolso foi recusado. O motivo vem em decision_reason.
refund.failedO envio do reembolso falhou. O valor voltou ao seu saldo.
withdrawal.requestedVocê pediu um saque.
withdrawal.approvedO saque foi aprovado e vai ser pago.
withdrawal.paidO saque foi pago na sua conta.
withdrawal.rejectedO saque foi recusado. O motivo vem em reason.
withdrawal.failedO envio do saque falhou. O valor voltou ao seu saldo.
infraction.openedUm cliente abriu uma contestação. O valor ficou retido.
infraction.updatedA 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çalhoO que é
Webhook-IdO id do evento. É o mesmo em todos os reenvios.
Webhook-TimestampHorário deste envio, em segundos Unix.
Webhook-SignatureA assinatura: v1= seguido de 64 caracteres hexadecimais.
Content-Typeapplication/json

Como validar a assinatura

  1. Leia o corpo cru da requisição, antes de qualquer conversão de JSON.
  2. Monte o texto Webhook-Id + . + Webhook-Timestamp + . + corpo cru.
  3. Calcule o HMAC-SHA256 desse texto. A chave é o segredo inteiro, com o prefixo whsec_.
  4. Escreva o resultado em hexadecimal minúsculo e coloque v1= na frente.
  5. Compare com Webhook-Signature usando comparação de tempo constante.
  6. Recuse se o Webhook-Timestamp estiver 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" -hex

Reenvios

  • Um envio dá certo quando o seu servidor responde 2xx em 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 status de data e o horário created_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 2xx rá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.