*.v1) — mudanças incompatíveis geram uma nova versão, nunca quebram seu consumidor. Você escolhe explicitamente os tipos que quer receber ao criar a assinatura.
Pagamentos
Refunds
Saques
Disputas
Conta
Assinaturas recorrentes
Eventos do ciclo de vida das assinaturas que seus clientes contratam. Cada fato do ciclo de vida gera um evento, publicado no ambiente (test ou live) da própria assinatura.
Campos do payload
O objetodata é um snapshot da assinatura no momento do evento. Campos sem valor são omitidos (não chegam como null).
cancellation_reason
expiration_reason
Ordem e duplicidade
Webhooks podem chegar fora de ordem ou repetidos. Guarde o maiorversion processado por assinatura e ignore eventos com version menor ou igual. Para deduplicar a entrega em si, use o id do envelope.
subscription.renewed.v1
Testar no sandbox
Com uma assinatura de teste, usePOST /v1/test/subscriptions/{id}/simulate (veja Sandbox) para avançar o ciclo sem esperar o calendário: PAY_INVOICE gera subscription.activated.v1 (primeira fatura) ou subscription.renewed.v1, e FAIL_INVOICE gera subscription.payment_failed.v1. Cancelar pela API gera subscription.canceled.v1.
Formato do payload
Toda entrega tem o mesmo envelope. O conteúdo dedata varia por tipo de evento.
payment.succeeded.v1
- Campos são
snake_case;amount_minorem centavos (BRL). - O snapshot traz os campos relevantes de cada tipo (ex.:
refund_initiatorereview_deadline_atem eventos de refund). Campos sem valor são omitidos. - Dados pessoais do comprador (documento, e-mail, telefone, endereço) e dados de cartão nunca vão no payload. Consulte a API quando precisar deles.
- O objeto acima é o corpo da requisição. Os cabeçalhos de assinatura seguem o padrão Svix; veja Verificação de assinatura.
Este catálogo é a fonte oficial dos tipos versionados. Novos eventos podem ser adicionados mantendo a versão; assine só o que sua integração consome.