Webhooks

Registre URLs para receber eventos de cobranças, clientes, transferências, estornos, contestações, faturas, assinaturas e sessões de checkout. Cadastre inscrições pela API (Criar webhook); falhas de entrega aparecem em Logs de entrega.

Montagem básica

Exponha uma rota POST (ex.: /webhooks/upag) com TLS.
Crie o webhook com POST /v1/webhooks, informando url e events, e guarde o secret (whsec_...).
Valide a assinatura sobre o corpo bruto (Verificação e segurança), trate o JSON e responda 2xx.

Node.js SDK

import { Upag } from 'upag';

const upag = new Upag('sk_test_your_api_key');

const webhook = await upag.webhooks.create({
  url: 'https://example.com/webhooks/upag',
  events: ['charge.paid', 'transfer.completed'],
});

console.log(webhook.secret); // whsec_...

Sandbox e produção

Use sk_test_... contra https://api.upag.dev/v1 e sk_live_... contra https://api.upag.io/v1. Cadastre webhooks separados em cada ambiente para não processar evento de teste como produção.

Envelope

Cada entrega é um POST com corpo JSON:

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "event": "charge.paid",
  "createdAt": "2026-03-18T12:05:00.000Z",
  "data": { }
}

Campo	Uso
`id`	UUID desta entrega (idempotência)
`event`	Nome do evento (tabelas abaixo)
`createdAt`	ISO 8601 do momento do envio
`data`	Recurso serializado como a API o retorna; entidades relacionadas vêm como id, nunca expandidas

Headers enviados em cada entrega:

Header	Valor
`Content-Type`	`application/json`
`X-Webhook-Id`	Mesmo valor de `id` no corpo
`X-Webhook-Event`	Mesmo valor de `event` no corpo
`X-Webhook-Signature`	`sha256=<hex>` — ver Verificação e segurança

Os headers definidos no cadastro do webhook são aplicados por último: um header customizado com um desses nomes sobrescreve o nosso. Use nomes distintos. data é um retrato do recurso no instante do evento, não uma leitura atual. Em charge.paid, por exemplo, status já é paid, mas splits ainda pode vir vazio; consulte a cobrança quando precisar do estado atual.

Assinar eventos

Informe em events ao menos um evento ao criar ou atualizar o webhook. Um webhook só recebe os eventos listados e enquanto active for true. Um valor fora da lista abaixo é rejeitado com erro de validação.

Eventos

Uma mudança de status dispara dois eventos: o específico e o *.updated correspondente (por exemplo charge.paid e charge.updated). Assine só um deles, a menos que queira tratar os dois.

Cobranças

Evento	Quando
`charge.created`	Cobrança criada
`charge.paid`	Cobrança paga
`charge.expired`	Cobrança expirou sem pagamento
`charge.refunded`	Cobrança estornada por completo
`charge.partially_refunded`	Estorno parcial
`charge.failed`	Cartão: pagamento recusado ou captura falhou
`charge.in_review`	Cartão: autorizada e retida para análise antifraude
`charge.chargeback`	Cartão: chargeback aberto pelo portador
`charge.updated`	Qualquer mudança de status, junto do evento específico

data: Payload cobrança.

Clientes

Evento	Quando
`customer.created`	Cliente criado (inclui criação inline numa cobrança)
`customer.updated`	Cliente atualizado

data: Payload cliente.

Transferências

Evento	Quando
`transfer.created`	Transferência criada, em qualquer direção
`transfer.processing`	Pix enviado ao provedor, aguardando liquidação
`transfer.completed`	Transferência liquidada
`transfer.failed`	Transferência rejeitada pelo provedor
`transfer.updated`	Qualquer mudança de status, junto do evento específico

data: Payload transferência.

Um Pix recebido direto numa das suas chaves, sem cobrança, vira uma transferência com direction: "in": dispara transfer.created, transfer.completed e transfer.updated em sequência (sem transfer.processing). Só o Pix que quita uma cobrança sua dispara charge.paid. Para detectar entrada de dinheiro, assine também transfer.completed.

Estornos

Evento	Quando
`refund.created`	Estorno criado
`refund.processing`	Estorno aceito pelo provedor, aguardando liquidação
`refund.completed`	Estorno liquidado
`refund.failed`	Estorno rejeitado; o valor reservado é liberado
`refund.updated`	Qualquer mudança de status, junto do evento específico

data: Payload estorno.

Contestações

Evento	Quando
`dispute.created`	Contestação aberta
`dispute.resolved`	Contestação finalizada (`won` ou `lost`)
`dispute.updated`	Qualquer mudança de status, junto do evento específico

data: Payload contestação.

Faturas

Evento	Quando
`invoice.created`	Fatura criada, já com seus itens
`invoice.opened`	Fatura aberta
`invoice.paid`	Fatura paga
`invoice.voided`	Fatura anulada
`invoice.uncollectible`	Fatura marcada como incobrável
`invoice.payment_failed`	Tentativa de pagamento da fatura falhou

data: Payload fatura.

Assinaturas

Evento	Quando
`subscription.created`	Assinatura criada (seguido de `subscription.incomplete`)
`subscription.active`	Assinatura ativa
`subscription.trialing`	Assinatura em período de teste
`subscription.trial_ending`	Faltam 3 dias para o fim do teste; enviado uma vez por teste
`subscription.past_due`	Assinatura em atraso
`subscription.incomplete`	Assinatura incompleta
`subscription.paused`	Assinatura pausada
`subscription.canceled`	Assinatura cancelada
`subscription.void`	Assinatura anulada

data: Payload assinatura.

Sessões de checkout

Evento	Quando
`checkout-session.created`	Sessão criada
`checkout-session.completed`	Pagador concluiu o checkout
`checkout-session.expired`	Sessão expirou

data: Payload checkout.

A API aceita em events alguns nomes que não são emitidos hoje: charge.pending, invoice.updated, invoice.drafted, subscription.updated, checkout-session.opened, checkout-session.updated, além dos prefixos legados payment.*, product.* e price.*. Inscrever-se neles não gera entregas. Não dependa deles.

Entrega e novas tentativas

Cada evento gera uma tentativa de POST por webhook ativo inscrito. Não há retentativa automática.
Qualquer status 2xx é sucesso. Outro status, timeout ou falha de conexão grava a tentativa como falha no log de entrega.
Reenvie uma tentativa falha com Reprocessar log. O reenvio usa o mesmo id e o mesmo corpo, assinado de novo com o secret atual, e grava um novo log.
Entregas são independentes: não há garantia de ordem entre eventos. Use updatedAt em data para descartar retratos mais antigos.

Idempotência

Deduplique por id (ou pelo header X-Webhook-Id) antes de qualquer efeito colateral. Um reenvio reaproveita o id original.

Devolva 2xx só depois de persistir ou enfileirar o trabalho; handlers lentos viram entregas falhas.
Campos novos podem aparecer em data sem aviso: leia só o que você usa.

const deliveryId = body.id;
if (await processed.has(deliveryId)) return res.sendStatus(200);
await enqueue(body);
await processed.add(deliveryId);
return res.sendStatus(200);

Referência de payloads

Cobrança

Eventos charge.*.

Transferência

Eventos transfer.*.

Cliente

Eventos customer.*.

Estorno

Eventos refund.*.

Contestação

Eventos dispute.*.

Fatura

Eventos invoice.*.

Assinatura

Eventos subscription.*.

Checkout

Eventos checkout-session.*.

Objeto webhook na API: Referência. Validação no SDK: SDK servidor.

Visão geral

Referência

Segurança

Endpoints

Payloads

Logs de entrega

Montagem básica

Sandbox e produção

Envelope

Assinar eventos

Eventos

Cobranças

Clientes

Transferências

Estornos

Contestações

Faturas

Assinaturas

Sessões de checkout

Entrega e novas tentativas

Idempotência

Referência de payloads

Cobrança

Transferência

Cliente

Estorno

Contestação

Fatura

Assinatura

Checkout

​Montagem básica

​Sandbox e produção

​Envelope

​Assinar eventos

​Eventos

​Cobranças

​Clientes

​Transferências

​Estornos

​Contestações

​Faturas

​Assinaturas

​Sessões de checkout

​Entrega e novas tentativas

​Idempotência

​Referência de payloads

Cobrança

Transferência

Cliente

Estorno

Contestação

Fatura

Assinatura

Checkout

Montagem básica

Sandbox e produção

Envelope

Assinar eventos

Eventos

Cobranças

Clientes

Transferências

Estornos

Contestações

Faturas

Assinaturas

Sessões de checkout

Entrega e novas tentativas

Idempotência

Referência de payloads