> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upag.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhooks Billing: eventos payment, subscription e invoice, assinatura HMAC e payloads.

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

1. Exponha uma rota POST (ex.: `/webhooks/upag-billing`) com TLS.
2. No dashboard Billing, informe a URL e marque os eventos ([Referência](./reference)).
3. 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

```json theme={null}
{
  "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](#referencia-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](./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](./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](./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](./security).

## 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.

```javascript theme={null}
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

<CardGroup cols={3}>
  <Card title="Payment" icon="credit-card" href="./payload-payment">
    Campos em `payment.*`.
  </Card>

  <Card title="Subscription" icon="repeat" href="./payload-subscription">
    Campos em `subscription.*`.
  </Card>

  <Card title="Invoice" icon="file-invoice" href="./payload-invoice">
    Campos em `invoice.*`.
  </Card>
</CardGroup>

## Guias

<CardGroup cols={2}>
  <Card title="Checkout hospedado" icon="cart-shopping" href="../guides/checkout-hosted">
    Sessão, redirect e handler de pagamento.
  </Card>

  <Card title="Assinatura recorrente" icon="calendar" href="../guides/subscription-recurring">
    Ciclo de assinatura e fatura.
  </Card>
</CardGroup>