Webhooks

Webhooks — Transações PIX

Receba notificações em tempo real sempre que o status de uma transação PIX mudar. Configure a URL de webhook ao criar a transação.

Como Funciona

Ao criar uma transação com o campo webhook_url, nossa plataforma enviará uma requisição POST para essa URL toda vez que o status da transação mudar. Você deve responder com HTTP 200 para confirmar o recebimento.

Configuração do Endpoint

Método	POST
Content-Type	application/json
Timeout	Responda o mais rápido possível
Resposta esperada	HTTP 200

Payload do Webhook

Interface TypeScripttypescript

interface TransactionWebhook {
  id: string;
  external_id: string | null;
  total_amount: number;
  status: "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE";
  payment_method: string;
}

Exemplo de Payload

Notificação de Pagamento Confirmadojson

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "total_amount": 100.50,
  "status": "AUTHORIZED",
  "payment_method": "PIX"
}

Campos do Payload

Campo	Tipo	Descrição
`id`	`string (UUID)`	ID único da transação
`external_id`	`string \| null`	Sua referência interna informada na criação
`total_amount`	`number`	Valor total da transação em BRL
`status`	`string`	Novo status: AUTHORIZED, PENDING, CHARGEBACK, FAILED ou IN_DISPUTE
`payment_method`	`string`	Método de pagamento (ex: PIX)

Implementação de Exemplo

Node.js + Expressjavascript

app.post('/webhooks/transactions', (req, res) => {
  const { id, external_id, total_amount, status, payment_method } = req.body;
  
  // Responda imediatamente com 200 antes de processar
  res.status(200).json({ received: true });

  // Processe o evento de forma assíncrona
  setImmediate(() => {
    switch (status) {
      case 'AUTHORIZED':
        // Pagamento confirmado — libere o pedido/serviço
        liberarPedido(id, external_id);
        break;
      case 'FAILED':
        // Pagamento falhou — notifique o cliente
        notificarFalha(id, external_id);
        break;
      case 'CHARGEBACK':
        // Contestação iniciada — acione o time de suporte
        abrirChamado(id, external_id);
        break;
    }
  });
});

Boas Práticas

Responda com HTTP 200

Sempre responda antes de processar para evitar timeout.

Processe de forma assíncrona

Execute a lógica de negócio em background para agilizar a resposta.

Implemente idempotência

Webhooks podem ser reentregues. Use o campo id para deduplicar eventos.

Registre os recebimentos

Mantenha logs de todos os webhooks recebidos para debugging.

Valide o evento antes de agir

Confirme o status consultando a transação diretamente pela API antes de realizar ações críticas.

Use HTTPS

Seu endpoint de webhook deve estar em HTTPS para segurança.

Configure o campo webhook_url ao criar a transação com POST /v1/transactions. A URL deve ser publicamente acessível e responder em HTTPS.