> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Webhooks

> Handle recurring billing events with the subscription webhook envelope and event names.

Subscription webhooks use a dedicated envelope. The top-level `event` is always `subscription`; the concrete event name is in `data.event_type`.

## Example delivery payload

```json theme={null}
{
  "api_version": "v2",
  "id": "120ebf7cc24835b5ea33ee617bf70cb91c3a4dcd7413afcb05f61c60d1c9de3d",
  "event": "subscription",
  "url": "https://merchant.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",
    "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"
    }
  }
}
```

Failure events include the same subscription fields plus retry context such as `attempt_number` and `failure_reason`.

## 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`

## Handling guidance

* Deduplicate by the top-level event `id`.
* Use `data.event_type` to route business logic.
* Use `data.status` for the current subscription state.
* Use `latest_transaction` for the billing transaction linked to the event.
* Use `data.id`, not a numeric database id, as the public subscription identifier.
* Reconcile with `GET /v2/subscriptions/{id}` if delivery or processing is interrupted.

## Read next

* [Webhooks Overview](/webhooks/overview)
* [Subscription Lifecycle](/subscriptions/lifecycle)
* [API: Get a Subscription](/api-reference/subscriptions/get)