Subscription Webhooks

​

Example delivery payload

{
  "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"
    }
  }
}

​

Events emitted today

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

​

Pix Automático sequence

• Without a trial: no event at creation. subscription.started, with previous_status: "incomplete", arrives once the payer has authorized and the first debit is paid.
• With a trial: subscription.created arrives when the payer approves the authorization (status trialing, latest_transaction: null). subscription.trial_will_end arrives 3 days before trial_end if the subscription is already trialing by then, and subscription.started with the first debit after it.
• Rejected authorization, or, depending on the account configuration, an expired one: subscription.canceled, with failure_reason.
• Later cycles: subscription.renewed for each paid debit. After a failed debit, subscription.payment_failed, plus subscription.past_due when the subscription moves to past_due.
• Cancellation: subscription.canceled, never subscription.updated.

​

Plan changes

{
  "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"
  }
}

• A scheduled change was cancelled. You receive subscription.updated with update_fields: ["pending_change"] and no plan_change block.
• A scheduled change took effect at renewal. No subscription.updated is sent for it. You receive the usual subscription.renewed, already carrying the new amount, and pendingChange is null on the next read.

​

Handling guidance

• Deduplicate by the top-level event id.
• Use data.event_type to route each event to the correct handler.
• Use data.status for the current subscription state.
• Use latest_transaction for the billing transaction linked to the event. On Pix Automático failure events, it is the most recent transaction of the subscription.
• Use the UUID in data.id as the subscription identifier.
• Reconcile with GET /v2/subscriptions/{id} if delivery or processing is interrupted.

​

Read next

• Webhooks Overview
• Pix Automático Subscriptions
• Subscription Lifecycle
• API: Get a Subscription