# Source: https://polar.sh/docs/integrate/webhooks/events.md

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

# Webhook Events

> Our webhook events and in which context they are useful

## Billing Events

### Checkout

<Columns cols={2}>
  <Card title="checkout.created" icon="link" href="/api-reference/webhooks/checkout.created" horizontal />

  <Card title="checkout.updated" icon="link" href="/api-reference/webhooks/checkout.updated" horizontal />
</Columns>

### Customers

<Columns cols={2}>
  <Card title="customer.created" icon="link" href="/api-reference/webhooks/customer.created" horizontal>
    Fired when a new customer has been created.
  </Card>

  <Card title="customer.updated" icon="link" href="/api-reference/webhooks/customer.updated" horizontal>
    Fired when a customer has been updated.
  </Card>

  <Card title="customer.deleted" icon="link" href="/api-reference/webhooks/customer.deleted" horizontal>
    Fired when a customer has been deleted.
  </Card>

  <Card title="customer.state_changed" icon="link" href="/api-reference/webhooks/customer.state_changed" horizontal>
    Fired when a customer's state has changed. Includes active subscriptions and
    granted benefits.
  </Card>
</Columns>

### Subscriptions

In order to properly implement logic for handling subscriptions, you should look into the following events.

<Columns cols={2}>
  <Card title="subscription.created" icon="link" href="/api-reference/webhooks/subscription.created" horizontal>
    Fired when a new subscription has been created.
  </Card>

  <Card title="subscription.active" icon="link" href="/api-reference/webhooks/subscription.active" horizontal />

  <Card title="subscription.uncanceled" icon="link" href="/api-reference/webhooks/subscription.uncanceled" horizontal />

  <Card title="subscription.canceled" icon="link" href="/api-reference/webhooks/subscription.canceled" horizontal />

  <Card title="subscription.past_due" icon="link" href="/api-reference/webhooks/subscription.past_due" horizontal>
    Fired when a subscription payment has failed. The customer can recover by updating their payment method.
  </Card>

  <Card title="subscription.updated" icon="link" href="/api-reference/webhooks/subscription.updated" horizontal>
    Use this event if you want to handle cancellations, un-cancellations, etc. The
    updated event is a catch-all event for `subscription.active`,
    `subscription.canceled`, `subscription.uncanceled`, `subscription.past_due` and `subscription.revoked`.
  </Card>

  <Card title="order.created" icon="link" href="/api-reference/webhooks/order.created" horizontal>
    In case you want to do logic when a subscription is renewed, you should listen
    to `order.created` and the `billing_reason` field. It can be `purchase`,
    `subscription_create`, `subscription_cycle` and `subscription_update`.
    `subscription_cycle` is used when subscriptions renew.
  </Card>

  <Card title="subscription.revoked" icon="link" href="/api-reference/webhooks/subscription.revoked" horizontal />
</Columns>

#### Cancellation Sequences

When a subscription is canceled, the events triggered depend on whether the cancellation is immediate or scheduled for the end of the billing period.

**End-of-Period Cancellation (default)**

When a subscription is **canceled** (by customer action from the portal or by the merchant from the dashboard/API), the following events are sent immediately:

1. `subscription.updated`
2. `subscription.canceled`

Both events contain the same subscription data. The subscription will still have `active` status, but the `cancel_at_period_end` flag will be set to `true`.

When the end of the current billing period arrives, the subscription is definitively revoked: billing cycles stop and benefits are revoked. The following events are then sent:

3. `subscription.updated`
4. `subscription.revoked`

Both events contain the same subscription data. The subscription will have the `canceled` status.

**Immediate Revocation**

When a merchant cancels a subscription with **immediate revocation**, those events are sent at once:

1. `subscription.updated`
2. `subscription.canceled`
3. `subscription.revoked`

All three events contain the same subscription data. The subscription will have the `canceled` status immediately.

#### Renewal Sequences

When a subscription is renewed for a new cycle, the webhook events are triggered in a specific sequence to help you track the renewal process and handle billing logic appropriately.

**Initial Renewal Events**

When a subscription reaches its renewal date, the following events are sent immediately (if enabled on the webhook):

1. `subscription.updated`
2. `order.created`

The subscription data will reflect the new billing period through the `current_period_start` and `current_period_end` properties, showing the updated cycle dates.

The order data represents the new invoice for the upcoming cycle, with a total representing what the customer will pay for this new period. If usage-based billing is involved, their consumption for the past period will be included in the total. The status of this order is `pending` at this stage.

**Payment Processing Events**

Shortly after the initial renewal events, the platform will trigger a payment for the new order. Once the payment is successfully processed, the following events are sent:

3. `order.updated`
4. `order.paid`

Both events will contain the same order data, with the order status changed to `paid`.

### Orders

<Columns cols={2}>
  <Card title="order.created" icon="link" href="/api-reference/webhooks/order.created" horizontal />

  <Card title="order.paid" icon="link" href="/api-reference/webhooks/order.paid" horizontal />

  <Card title="order.updated" icon="link" href="/api-reference/webhooks/order.updated" horizontal />

  <Card title="order.refunded" icon="link" href="/api-reference/webhooks/order.refunded" horizontal />
</Columns>

### Refunds

<Columns cols={2}>
  <Card title="refund.created" icon="link" href="/api-reference/webhooks/refund.created" horizontal />

  <Card title="refund.updated" icon="link" href="/api-reference/webhooks/refund.updated" horizontal />
</Columns>

### Benefit Grants

<Columns cols={2}>
  <Card title="benefit_grant.created" icon="link" href="/api-reference/webhooks/benefit_grant.created" horizontal />

  <Card title="benefit_grant.updated" icon="link" href="/api-reference/webhooks/benefit_grant.updated" horizontal />

  <Card title="benefit_grant.revoked" icon="link" href="/api-reference/webhooks/benefit_grant.revoked" horizontal />
</Columns>

## Organization Events

### Benefits

<Columns cols={2}>
  <Card title="benefit.created" icon="link" href="/api-reference/webhooks/benefit.created" horizontal />

  <Card title="benefit.updated" icon="link" href="/api-reference/webhooks/benefit.updated" horizontal />
</Columns>

### Products

<Columns cols={2}>
  <Card title="product.created" icon="link" href="/api-reference/webhooks/product.created" horizontal />

  <Card title="product.updated" icon="link" href="/api-reference/webhooks/product.updated" horizontal />
</Columns>

### Organization

<Columns cols={2}>
  <Card title="organization.updated" icon="link" href="/api-reference/webhooks/organization.updated" horizontal />
</Columns>