Webhooks

No Billing, webhooks avisam sua aplicação quando pagamentos, assinaturas ou faturas mudam. Você registra uma URL HTTPS no dashboard, escolhe os eventos e passa a receber POST com event e data. Consultar a API de tempos em tempos ainda serve para suporte ou telas administrativas; para disparar automação (ERP, e-mail transacional, liberação de produto), o webhook costuma ser o caminho mais simples.

Montagem básica

Exponha uma rota POST (ex.: /webhooks/upag-billing) com TLS.
No dashboard Billing, informe a URL e marque os eventos (Referência).
Valide a assinatura, trate o JSON, responda status 2xx quando aceitar a entrega.

O retorno do checkout no browser pode falhar (aba fechada, rede). Trate payment.approved ou invoice.paid no servidor como confirmação do negócio.

Sandbox vs live

Mantenha URLs ou configurações distintas para contas/chaves sk_test_... e sk_live_..., para não processar evento de teste como produção.

Envelope

{
  "event": "payment.approved",
  "data": { }
}

Campo	Uso
`event`	Identificador (`subscription.created`, `payment.approved`, …). Roteie o handler por este valor.
`data`	Snapshot do recurso. Formato por família — links na seção Referência de payloads.

Eventos

Assinaturas

Evento	Descrição
`subscription.created`	Nova assinatura criada
`subscription.active`	Assinatura ativa
`subscription.canceled`	Assinatura cancelada
`subscription.past_due`	Assinatura em atraso
`subscription.trialing`	Período de trial
`subscription.incomplete`	Assinatura incompleta
`subscription.paused`	Assinatura pausada
`subscription.void`	Assinatura anulada

data: Payload Subscription.

Pagamentos

Evento	Descrição
`payment.created`	Novo pagamento criado
`payment.incomplete`	Pagamento incompleto
`payment.pending`	Pagamento pendente
`payment.approved`	Pagamento aprovado
`payment.refunded`	Pagamento reembolsado
`payment.refused`	Pagamento recusado
`payment.failed`	Pagamento falhou

data: Payload Payment.

Faturas

Evento	Descrição
`invoice.created`	Nova fatura criada
`invoice.opened`	Fatura aberta
`invoice.paid`	Fatura paga
`invoice.voided`	Fatura anulada

data: Payload Invoice.

Autenticidade

Confira HMAC do corpo com a signing secret do endpoint e o header indicado no dashboard (ex.: x-upag-signature). Passo a passo: Verificação e segurança.

Entregas repetidas

O Billing pode reenviar o mesmo evento após timeout ou erro HTTP. Guarde um registro por ${event}:${data.id} antes de efeitos colaterais.

Devolva 2xx só depois de persistir ou enfileirar.
Não amarre validação a um schema fixo de todo o data — campos novos podem surgir sem aviso de versão na doc.

const key = `${body.event}:${body.data?.id}`;
if (await processed.has(key)) return res.sendStatus(200);
await enqueue(body);
await processed.add(key);
return res.sendStatus(200);

Referência de payloads

Payment

Campos em payment.*.

Subscription

Campos em subscription.*.

Invoice

Campos em invoice.*.

Guias

Checkout hospedado

Sessão, redirect e handler de pagamento.

Assinatura recorrente

Ciclo de assinatura e fatura.

Visão geral

Referência

Segurança

Payloads

Montagem básica

Sandbox vs live

Envelope

Eventos

Assinaturas

Pagamentos

Faturas

Autenticidade

Entregas repetidas

Referência de payloads

Payment

Subscription

Invoice

Guias

Checkout hospedado

Assinatura recorrente

​Montagem básica

​Sandbox vs live

​Envelope

​Eventos

​Assinaturas

​Pagamentos

​Faturas

​Autenticidade

​Entregas repetidas

​Referência de payloads

Payment

Subscription

Invoice

​Guias

Checkout hospedado

Assinatura recorrente

Montagem básica

Sandbox vs live

Envelope

Eventos

Assinaturas

Pagamentos

Faturas

Autenticidade

Entregas repetidas

Referência de payloads

Guias