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

# Webhooks de Assinaturas

> Eventos de assinatura, payload base e campos extras por evento.

Todos os eventos de assinatura seguem o mesmo envelope. Cadastre os eventos desejados em `POST /api/v1/user/company/webhooks`.

## Eventos disponíveis

| Evento                         | Quando é disparado                               |
| ------------------------------ | ------------------------------------------------ |
| `subscription.created`         | Assinatura criada                                |
| `subscription.trial_started`   | Assinatura criada com trial                      |
| `subscription.activated`       | Primeiro ciclo pago com sucesso (trial encerrou) |
| `subscription.paused`          | Assinatura pausada                               |
| `subscription.resumed`         | Assinatura retomada                              |
| `subscription.plan_changed`    | Plano alterado (imediato ou agendado)            |
| `subscription.payment.success` | Ciclo cobrado com sucesso                        |
| `subscription.payment.failed`  | Tentativa de cobrança falhou                     |
| `subscription.payment.retry`   | Retentativa agendada                             |
| `subscription.past_due`        | Todas as retentativas esgotadas                  |
| `subscription.canceled`        | Assinatura cancelada                             |

***

## Payload base

Todos os eventos incluem estes campos:

```json theme={null}
{
  "event": "subscription.payment.success",
  "subscription_id": "01a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "plan_id": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
  "customer_id": 42,
  "status": "active",
  "amount": 2093,
  "currency": "BRL",
  "interval": "monthly",
  "interval_count": 1,
  "billing_day": 10,
  "next_billing_at": "2026-08-10T00:00:00+00:00",
  "current_period": {
    "start": "2026-07-10T00:00:00+00:00",
    "end": "2026-08-10T00:00:00+00:00"
  },
  "trial": null,
  "created_at": "2026-06-25T12:00:00+00:00"
}
```

***

## Campos extras por evento

| Evento                         | Campos adicionais                                                              |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `subscription.trial_started`   | `trial_end`                                                                    |
| `subscription.canceled`        | `at_period_end`                                                                |
| `subscription.paused`          | `paused_until`                                                                 |
| `subscription.plan_changed`    | `new_plan_id`, `change_type` (`upgrade\|downgrade`), `immediately`, `executed` |
| `subscription.payment.success` | `cycle_id`, `amount_charged`, `transaction_id`                                 |
| `subscription.payment.failed`  | `cycle_id`, `retry_count`, `next_retry_at`, `final`                            |
| `subscription.payment.retry`   | `cycle_id`, `retry_count`, `next_retry_at`                                     |
| `subscription.past_due`        | `cycle_id`, `retry_count`, `reason`                                            |

<Warning>
  Implemente todos os eventos de `subscription.payment.*` e `subscription.past_due`. São eles que sinalizam quando o acesso do cliente deve ser suspenso ou reativado.
</Warning>