Skip to main content
Os tipos de evento são versionados (*.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.
Para liberar ou bloquear acesso ao seu produto, use access_until, não só o status: uma assinatura PAST_DUE (em carência) ou CANCELED continua com acesso até essa data. O acesso termina de fato quando chega subscription.expired.v1.

Campos do payload

O objeto data é 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 maior version 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, use POST /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 de data varia por tipo de evento.
payment.succeeded.v1
  • Campos são snake_case; amount_minor em centavos (BRL).
  • O snapshot traz os campos relevantes de cada tipo (ex.: refund_initiator e review_deadline_at em 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.