Webhooks

Registre URLs HTTPS para receber eventos de cobranças, transferências, clientes, estornos e contestações. 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-core) com TLS.
Crie o webhook com POST /v1/webhooks e guarde o secret (whsec_...).
Valide a assinatura, trate o JSON, responda 2xx quando aceitar a entrega.

Sandbox vs live

Use chaves sk_test_... e sk_live_... em ambientes separados para não processar evento de teste como produção.

Envelope

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

Campo	Uso
`id`	Identificador desta entrega (idempotência)
`event`	Identificador do evento (tabelas abaixo)
`createdAt`	ISO 8601 do envio
`data`	Recurso serializado — links na seção Referência de payloads

Eventos

Cobranças

Evento	Descrição
`charge.created`	Cobrança criada
`charge.updated`	Cobrança atualizada
`charge.pending`	Cobrança pendente
`charge.paid`	Cobrança paga
`charge.expired`	Cobrança expirada
`charge.refunded`	Cobrança estornada
`charge.partially_refunded`	Estorno parcial

data: Payload cobrança.

Clientes

Evento	Descrição
`customer.created`	Cliente criado
`customer.updated`	Cliente atualizado

data: Payload cliente.

Transferências

Evento	Descrição
`transfer.created`	Transferência criada
`transfer.updated`	Transferência atualizada
`transfer.processing`	Em processamento
`transfer.completed`	Concluída
`transfer.failed`	Falhou

data: Payload transferência.

Estornos e contestações

Evento	Descrição
`refund.created`	Estorno criado
`refund.updated`	Estorno atualizado
`refund.processing`	Estorno em processamento
`refund.completed`	Estorno concluído
`refund.failed`	Estorno falhou
`dispute.created`	Contestação criada
`dispute.updated`	Contestação atualizada
`dispute.resolved`	Contestação finalizada

Autenticidade

Confira HMAC do corpo com o secret do webhook e o header X-Webhook-Signature (sha256=...). Passo a passo: Verificação e segurança.

Entregas repetidas

A Core pode reenviar após timeout ou erro HTTP. Use payload.id ou ${event}:${data.id} antes de efeitos colaterais.

Devolva 2xx só depois de persistir ou enfileirar.
Campos novos podem aparecer em data sem aviso de versão na doc.

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

Referência de payloads

Cobrança

Eventos charge.*.

Transferência

Eventos transfer.*.

Cliente

Eventos customer.*.

Objeto webhook na API: Referência.

Visão geral

Referência

Segurança

Endpoints

Payloads

Logs de entrega

Montagem básica

Sandbox vs live

Envelope

Eventos

Cobranças

Clientes

Transferências

Estornos e contestações

Autenticidade

Entregas repetidas

Referência de payloads

Cobrança

Transferência

Cliente

​Montagem básica

​Sandbox vs live

​Envelope

​Eventos

​Cobranças

​Clientes

​Transferências

​Estornos e contestações

​Autenticidade

​Entregas repetidas

​Referência de payloads

Cobrança

Transferência

Cliente

Montagem básica

Sandbox vs live

Envelope

Eventos

Cobranças

Clientes

Transferências

Estornos e contestações

Autenticidade

Entregas repetidas

Referência de payloads