Webhooks

O sistema de webhooks da Pix Processamento envia notificações em tempo real sobre mudanças de status das suas transações. Quando você cria uma transação e fornece um callbackUrl, nosso sistema envia atualizações para essa URL toda vez que houver mudança de status.

O que é um webhook (callback)

Um webhook (também chamado de callback) é uma requisição POST que a Pix Processamento envia para o seu servidor quando algo acontece. Ao contrário da API normal (onde você chama a Pix Processamento), aqui é o oposto: a Pix Processamento chama você.

Pensa numa cobrança Pix. Você criou ela, exibiu o QR ao cliente, e agora precisa saber quando o cliente paga. Duas opções:

1. Polling, ficar perguntando a cada X segundos "já pagou? já pagou?" (custoso, lento, desnecessário).
2. Webhook, deixar a Pix Processamento te avisar assim que o pagamento entrar (instantâneo, eficiente, recomendado).

Duas formas de receber

As duas convivem. Se a transação tem callbackUrl e a conta tem webhook ativo, os dois recebem o mesmo payload.

Modo 1: callbackUrl na transação

A URL é informada a cada transação criada, no campo callbackUrl do body:

{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/pix",
  "clientReference": "pedido-2025-001"
}

A Pix Processamento vai enviar o callback para essa URL toda vez que aquela transação mudar de status (PENDING → COMPLETED, COMPLETED → REFUNDED, etc).

Modo 2: webhook cadastrado

Registre a URL uma vez, escolha os eventos e ganhe assinatura HMAC. Não precisa repetir callbackUrl em cada transação.

curl -X POST https://api.exemplo.processamento.com/v1/user/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com.br/webhooks/pix",
    "events": ["TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED"],
    "generateSecret": true
  }'

Eventos

Vale só para webhook cadastrado. Enviar events: [], ou omitir o campo, assina todos.

Headers do disparo

Assinatura HMAC

O valor de X-Callback-Signature tem duas partes: t, o timestamp Unix em segundos, e v1, o HMAC SHA-256 em hexadecimal calculado sobre a string <t>.<corpo cru da requisição> usando o secret como chave.

X-Callback-Signature: t=1746540312, v1=6f2c0e...9ab1

Use o corpo cru (a string recebida), não o objeto reserializado: qualquer mudança de espaçamento ou de ordem de chaves muda o hash.

import crypto from 'node:crypto';

app.post(
  '/webhooks/pix',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const header = req.get('X-Callback-Signature') ?? '';
    const parts = Object.fromEntries(
      header.split(',').map((part) => part.trim().split('=')),
    );
    const expected = crypto
      .createHmac('sha256', process.env.PIX_WEBHOOK_SECRET)
      .update(`${parts.t}.${req.body.toString('utf8')}`)
      .digest('hex');

    const ok =
      parts.v1?.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));

    if (!ok) return res.sendStatus(401);

    res.sendStatus(200);
    enqueue(JSON.parse(req.body.toString('utf8')), req.get('X-Callback-Event'));
  },
);

import hashlib, hmac, os
from flask import request, abort

@app.post("/webhooks/pix")
def pix_webhook():
    header = request.headers.get("X-Callback-Signature", "")
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    expected = hmac.new(
        os.environ["PIX_WEBHOOK_SECRET"].encode(),
        f'{parts.get("t", "")}.{request.get_data(as_text=True)}'.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(parts.get("v1", ""), expected):
        abort(401)

    enqueue(request.get_json(), request.headers.get("X-Callback-Event"))
    return "", 200

Sistema de retry

Os webhooks da Pix Processamento têm um sistema robusto de retentativa que garante a entrega mesmo em falhas temporárias. A Pix Processamento reenvia até 72 vezes o mesmo callback com backoff exponencial e jitter, distribuindo melhor a carga e evitando picos de requisições.

Segurança

Para garantir integridade e segurança, restrinja o acesso ao seu endpoint de webhook. Solicite o IP oficial da Pix Processamento ao suporte e aceite callbacks apenas dessa origem.

Com webhook cadastrado, some a isso a assinatura HMAC: o IP diz de onde veio, a assinatura prova que o corpo não foi adulterado. Se o secret vazar, rotacione em POST /user/webhooks/{id}/rotate-secret e faça o deploy do novo valor antes, porque o anterior é invalidado na hora.

Campos do payload

Identificação

Status e valores

Cobrança gerada (depósito)

Pagador

Recebedor

Em saques, os demais campos payer* descrevem a conta de liquidação do provedor, enquanto payerAccountNumber é a conta Pix Processamento que originou o saque. Para identificar uma transferência interna, use method: INTERNAL_TRANSFER, não a presença desses campos.

Saque via chave Pix

Liquidação e estorno

Timestamps

Infração (disputa Pix)

Boas práticas

• Responda rápido: devolva 2xx em menos de 5s. Processe pesado em fila/worker, não no handler.
• Idempotência: armazene id + status para deduplicar. O mesmo callback pode chegar mais de uma vez (retentativa, mudanças sucessivas).
• Use clientReference: passe um identificador externo na criação da transação. Volta no callback e facilita correlacionar com seu pedido.
• Restrinja por IP: aceite callbacks apenas do IP oficial da Pix Processamento.
• Valide a assinatura: em webhook cadastrado, rejeite com 401 todo disparo cuja X-Callback-Signature não bater.

Inspeção e reenvio

A API expõe a lista completa de callbacks enviados:

• GET /user/callbacks, lista paginada
• GET /user/callbacks/{id}, detalhes
• POST /user/callbacks/resend/{transactionId}, reenviar callback de uma transação
• POST /user/callbacks/resend, reenvio em lote
• POST /user/callbacks/resend/webhook/{webhookId}, reenvia tudo que falhou num webhook cadastrado

Para webhook cadastrado há ainda a contagem e o detalhe do disparo:

• GET /user/webhooks/sent/quantity, quantos disparos saíram
• GET /user/webhooks/{id}/sent/{callbackId}, payload, status e resposta de um disparo