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

# Webhooks de assinatura

> Consuma eventos de cobrança recorrente com o envelope e os nomes de evento 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

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

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`

## Guia de tratamento

* Faça deduplicação pelo `id` do evento no topo.
* Use `data.event_type` para rotear a lógica de negócio.
* Use `data.status` para o estado atual da assinatura.
* Use `latest_transaction` para a transação de cobrança ligada ao evento.
* Use `data.id`, não um ID numérico de banco, como identificador público da assinatura.
* Reconcilie com `GET /v2/subscriptions/{id}` se a entrega ou o processamento for interrompido.

## Leia a seguir

* [Visão geral de webhooks](/pt/webhooks/overview)
* [Ciclo de vida da assinatura](/pt/subscriptions/lifecycle)
* [API: Consultar assinatura](/pt/api-reference/subscriptions/get)