Eventos disponíveis

10 eventos cobrem o ciclo de vida de uma compra na Paguebase — do pagamento à revogação, passando por renovações de assinatura. Configure só os eventos que você precisa pra evitar tráfego desnecessário.

Evento	Descrição	Quando dispara
order.paid	Pedido pago	Pagamento confirmado. Em assinatura, dispara em TODA cobrança (primeira + renovações)
subscription.renewed	Assinatura renovada	Renovação de assinatura confirmada (a partir da 2ª cobrança)
access.granted	Acesso liberado	Comprador recebe acesso ao produto
access.revoked	Acesso revogado	Reembolso, disputa perdida ou revogação manual
trial.started	Trial iniciado	Comprador inicia período de teste
trial.expired	Trial expirado	Período de teste encerrou
refund.requested	Reembolso solicitado	Solicitação de reembolso criada pelo comprador
affiliate.commission_earned	Comissão gerada	Venda via afiliado confirmada (dispara em toda cobrança recorrente também)
member.enrolled	Membro inscrito	Novo membro recebeu acesso pela 1ª vez
checkout.abandoned	Checkout abandonado	Sessão sem conversão por 24h

Envelope de payload

Todos os eventos seguem o mesmo formato base:

Envelope

{
  "event": "order.paid",
  "data": { /* payload específico do evento */ },
  "timestamp": "2026-04-20T10:30:00.000Z"
}

Headers enviados

Header	Descrição
Content-Type	application/json
X-Paguebase-Signature	sha256=HMAC da payload (validar antes de processar)
X-Paguebase-Event	Nome do evento (ex: order.paid)
X-Paguebase-Delivery	UUID único de cada tentativa (use pra deduplicar)

Detalhes por evento

order.paid

Disparado após confirmação de pagamento via gateway. Em produtos one-time dispara uma única vez. Em assinaturas, dispara em toda cobrança confirmada (primeira + renovações) — use subscription.renewed se precisa distinguir venda nova de renovação.

data

{
  "order_id": "550e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-...",
  "amount": 97.00,
  "payment_method": "pix"
}

subscription.renewed

Disparado em renovações de assinatura (2ª cobrança em diante). Útil pra MRR tracking, email de agradecimento mensal, ou sincronização com CRM — sem precisar manter estado pra distinguir da compra inicial.

data

{
  "subscription_id": "ss0e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-...",
  "amount": 97.00
}

access.granted

Disparado simultaneamente a order.paid. Use se você só quer rastrear acesso (ignorando metadados de pagamento).

data

{
  "access_id": "880e8400-...",
  "order_id": "550e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-..."
}

access.revoked

Disparado quando o acesso é removido — reembolso, disputa perdida ou revogação manual via dashboard.

data

{
  "order_id": "550e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-...",
  "reason": "refunded" // refunded | disputed | manual | trial_expired | subscription_cancelled
}

trial.started

Disparado quando comprador inicia período de teste em produto recorrente com trial configurado.

data

{
  "order_id": "550e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-...",
  "trial_ends_at": "2026-05-04T10:30:00Z"
}

trial.expired

Disparado pelo cron quando trial expira. Antes do checkout cobrar a primeira mensalidade.

data

{
  "order_id": "550e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-...",
  "expired_at": "2026-05-04T10:30:00Z"
}

refund.requested

Disparado quando um pedido de reembolso é criado (via portal do comprador ou via API).

data

{
  "refund_id": "990e8400-...",
  "order_id": "550e8400-...",
  "amount": 97.00,
  "reason": "Cliente solicitou reembolso por insatisfação"
}

affiliate.commission_earned

Disparado após order.paid quando a venda veio por link de afiliado. A comissão é gravada com a porcentagem snapshot no momento da criação da order.

data

{
  "affiliate_id": "aa0e8400-...",
  "order_id": "550e8400-...",
  "product_id": "660e8400-...",
  "commission_amount": 9.70
}

member.enrolled

Disparado uma única vez por buyer × product na primeira liberação de acesso. Não dispara em renovação de assinatura.

data

{
  "member_id": "770e8400-...",
  "product_id": "660e8400-...",
  "buyer_id": "770e8400-...",
  "order_id": "550e8400-..."
}

checkout.abandoned

Disparado pelo cron quando uma sessão de checkout fica sem conversão por 24h. Use pra rastrear taxa de abandono em sistemas externos.

data

{
  "session_id": "bb0e8400-...",
  "product_id": "660e8400-...",
  "email": "comprador@email.com",
  "abandoned_at": "2026-04-20T10:30:00Z"
}

Ordem dos eventos numa compra típica

Sequência canônica numa venda de produto one-time via PIX, com afiliado:

Sequência (one-time)

1. checkout.abandoned    (se comprador abandonar 24h, opcional)
2. order.paid            (T+0s ao confirmar pagamento)
3. access.granted        (T+0s, simultâneo)
4. member.enrolled       (T+0s, se for primeira compra desse produto)
5. affiliate.commission_earned  (T+0s, se houve afiliado)

Sequência numa assinatura com trial:

Sequência (assinatura com trial)

1. trial.started              (T+0s na inscrição)
2. member.enrolled            (T+0s, primeira compra)
3. trial.expired              (Trial + N dias, cron noturno)
4. order.paid                 (1ª cobrança real após trial)
5. affiliate.commission_earned  (1ª cobrança, se houve afiliado)
6. order.paid + subscription.renewed  (todo mês, em cada renovação)
7. affiliate.commission_earned  (renovação, se houve afiliado)

Garantia de entrega: Paguebase tenta a entrega até 5 vezes com backoff exponencial (1m, 5m, 30m, 2h, 12h). Após 5 falhas, o evento entra na dead-letter queue e a entrega é marcada como falha.