Webhooks de assinatura

Webhooks de assinatura usam um envelope próprio. O event de topo é sempre subscription; o nome concreto do evento fica em data.event_type.

Exemplo de payload entregue

{
  "api_version": "v2",
  "id": "120ebf7cc24835b5ea33ee617bf70cb91c3a4dcd7413afcb05f61c60d1c9de3d",
  "event": "subscription",
  "url": "https://shop.example/webhooks/pagou",
  "data": {
    "id": "019e5d23-6ec8-73de-9c95-06093c62ba00",
    "cancel_at_period_end": false,
    "created_at": "2026-05-25T03:17:43.753Z",
    "current_period_start": "2026-05-25T03:17:43.752Z",
    "current_period_end": "2026-05-26T03:17:43.752Z",
    "cycle_count": 1,
    "failure_policy": "retry_then_cancel",
    "interval": "day",
    "interval_count": 1,
    "status": "active",
    "trial_end": null,
    "updated_at": "2026-05-25T03:17:46.219Z",
    "event_type": "subscription.created",
    "occurred_at": "2026-05-25T03:17:46.255Z",
    "customer_email": "buyer@example.com",
    "previous_status": null,
    "subscription_cycle": 1,
    "amount": 500,
    "currency": "BRL",
    "metadata": {
      "rtkcid": "clique-123",
      "utm_term": "black-friday"
    },
    "informations": [
      { "key": "rtkcid", "value": "clique-123" },
      { "key": "utm_term", "value": "black-friday" }
    ],
    "latest_transaction": {
      "id": "019e5d23-6ed7-7121-a667-41e5ac929c72",
      "correlation_id": "first_charge_13_1779679063767",
      "method": "credit_card",
      "status": "paid",
      "amount": 500,
      "currency": "BRL",
      "installments": 1,
      "paid_amount": "500",
      "paid_at": "2026-05-25T03:17:46.159Z"
    }
  }
}

Eventos de falha usam os mesmos campos da assinatura e também podem trazer contexto de retentativa, como attempt_number e failure_reason.

Eventos emitidos hoje

subscription.created
subscription.started
subscription.renewed
subscription.updated
subscription.canceled
subscription.payment_failed
subscription.past_due
subscription.trial_will_end
subscription.chargeback_received

Sequência do Pix Automático

Assinaturas com Pix Automático usam o mesmo envelope e os mesmos nomes de evento. O que muda é quando cada evento chega:

Sem período de teste: nenhum evento na criação. subscription.started, com previous_status: "incomplete", chega quando o pagador autorizou e o primeiro débito foi pago.
Com período de teste: subscription.created chega quando o pagador aprova a autorização (status trialing, latest_transaction: null). subscription.trial_will_end chega 3 dias antes de trial_end se a assinatura já estiver trialing nesse momento, e subscription.started com o primeiro débito depois dele.
Autorização recusada ou, dependendo da configuração da conta, expirada: subscription.canceled, com failure_reason.
Ciclos seguintes: subscription.renewed a cada débito pago. Depois de um débito com falha, subscription.payment_failed, e também subscription.past_due quando a assinatura passa para past_due.
Cancelamento: subscription.canceled, nunca subscription.updated.

Nesses eventos, latest_transaction.method é "pix". As cobranças do Pix Automático não enviam webhooks transaction.*, e um débito com falha não cria transação, então nos eventos de falha latest_transaction é a transação mais recente da assinatura. A tabela completa está em Assinaturas com Pix Automático.

Troca de plano

A troca de plano vale só para assinaturas com cartão. Uma troca de plano não cria um tipo de evento novo. Ela chega como subscription.updated, e update_fields diz o que se moveu: ["product_id", "amount"] quando o novo plano já está sendo cobrado, ["pending_change"] quando uma troca foi agendada ou uma troca agendada foi cancelada. Quando o plano de fato se move — na hora, ou no momento em que é agendado — o payload traz também um bloco plan_change:

{
  "event_type": "subscription.updated",
  "update_fields": ["product_id", "amount"],
  "plan_change": {
    "previous_product_id": "3f1a0f6e-0000-4000-8000-000000000101",
    "new_product_id": "3f1a0f6e-0000-4000-8000-000000000102",
    "effective_at": "2026-08-26T14:31:00.000Z"
  }
}

Numa troca agendada, effective_at é o fim do período atual; numa imediata, é o momento em que foi aplicada. Dois casos chegam sem plan_change de propósito, e é a ausência do bloco que os distingue dos anteriores:

Uma troca agendada foi cancelada. Você recebe subscription.updated com update_fields: ["pending_change"] e sem o bloco plan_change.
Uma troca agendada passou a valer na renovação. Nenhum subscription.updated é enviado por isso. Você recebe o subscription.renewed de sempre, já com o amount novo, e pendingChange fica null na leitura seguinte.

Guia de tratamento

Faça deduplicação pelo id do evento no topo.
Use data.event_type para encaminhar cada evento ao handler correto.
Use data.status para o estado atual da assinatura.
Use latest_transaction para a transação de cobrança ligada ao evento. Nos eventos de falha do Pix Automático, ela é a transação mais recente da assinatura.
Use o UUID em data.id como identificador da assinatura.
Reconcilie com GET /v2/subscriptions/{id} se a entrega ou o processamento for interrompido.

Cobrança recorrente

Exemplo de payload entregue

Eventos emitidos hoje

Sequência do Pix Automático

Troca de plano

Guia de tratamento

Leia a seguir

​Exemplo de payload entregue

​Eventos emitidos hoje

​Sequência do Pix Automático

​Troca de plano

​Guia de tratamento

​Leia a seguir

Exemplo de payload entregue

Eventos emitidos hoje

Sequência do Pix Automático

Troca de plano

Guia de tratamento

Leia a seguir