> ## Documentation Index > Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt > Use this file to discover all available pages before exploring further. # Webhook Events > Every webhook Macropay emits — what fires, when, and how to react to it in your billing logic. Webhooks are how your app stays in sync with everything happening inside Macropay — a checkout opening, a card clearing, a subscription lapsing, a benefit being revoked. Because Macropay is the **Merchant of Record**, many of these events also reflect work we handle on your behalf: tax/VAT collection, dispute management, and payment retries. You consume the event; we carry the compliance. This page is the catalog. Events are grouped by what they touch — money moving through a customer's lifecycle (**Billing**) and changes to your own catalog and account (**Organization**). Each card links to the full payload schema in the [API reference](/api-reference/webhooks/order.created). Subscribe to the narrowest events that satisfy your use case. Listening to a catch-all like `subscription.updated` is convenient, but the specific events (`subscription.canceled`, `order.paid`, etc.) make your handlers far easier to reason about. ## Billing events ### Checkout The session a customer moves through to pay. Useful for analytics, abandoned-checkout recovery, and pre-filling your own records before the order lands. A checkout session was opened. A checkout session changed status (e.g. confirmed or expired). ### Customers Track the people and organizations buying from you. `customer.state_changed` is the one to reach for when you need a single source of truth. A new customer record exists. Customer details were edited. A customer was removed. A consolidated snapshot whenever anything material changes — active subscriptions and currently granted benefits included. For provisioning access, `customer.state_changed` is usually all you need: the payload tells you exactly what the customer is entitled to right now, so you can reconcile your own access table in one place instead of stitching together subscription and benefit events. ### Subscriptions Recurring billing has the most moving parts, so it has the most events. Start here when implementing any subscription logic. A subscription was created. The subscription is active and billing. A scheduled cancellation was reversed. The subscription is set to cancel (or has canceled). A renewal payment failed. The customer can recover by updating their payment method — we retry automatically. Catch-all that fires alongside every other subscription event (`active`, `canceled`, `uncanceled`, `past_due`, `revoked`). Handy when you want one handler for all state transitions. Inspect the `billing_reason` field to tell renewals apart: `purchase`, `subscription_create`, `subscription_cycle`, or `subscription_update`. `subscription_cycle` means a renewal. Billing has stopped and benefits are gone — cut off access here. #### Cancellation flow What fires on cancellation depends on whether it takes effect at the end of the billing period (the default) or immediately. A customer cancels from the portal, or you cancel via the dashboard or API. Two events fire **right away**: 1. `subscription.updated` 2. `subscription.canceled` Both carry identical subscription data. The subscription stays in `active` status, but `cancel_at_period_end` is now `true` — so keep access on until the period ends. When the current period closes, the subscription is revoked for good: billing cycles stop and benefits are withdrawn. Two more events fire: 3. `subscription.updated` 4. `subscription.revoked` Both carry identical data, and the status is now `canceled`. When you cancel with **immediate revocation**, everything fires at once: 1. `subscription.updated` 2. `subscription.canceled` 3. `subscription.revoked` All three carry identical data and the status is `canceled` immediately. Revoke access on `subscription.revoked`. #### Renewal flow Each renewal cycle emits events in a fixed order so you can track the cycle from invoice to payment. At the renewal date, these fire immediately (if enabled on your endpoint): 1. `subscription.updated` 2. `order.created` The subscription now reflects the new `current_period_start` and `current_period_end`. The order is the invoice for the upcoming cycle with a `pending` status. If the plan uses **usage-based billing**, the customer's metered consumption for the prior period is already rolled into the total. We charge the new order shortly after. On success: 3. `order.updated` 4. `order.paid` Both carry the same order data, now with status `paid`. Treat `order.paid` as the green light to extend service for the new period. Metered, outcome, and agent-based plans settle through this same renewal flow. The `order.created` total for a usage plan already includes everything ingested through your meters during the period — including AI usage billed by tokens, activity, or verified outcome — so there is no separate "usage" event to reconcile. See [usage-based billing](/features/usage-based-billing/introduction) for how that consumption is aggregated. ### Orders A one-time purchase or a subscription invoice. These are your canonical revenue events. An order (invoice) was created. Payment cleared — recognize revenue and fulfill here. An order's status or details changed. An order was fully or partially refunded. ### Refunds Standalone refund lifecycle events, complementing `order.refunded`. A refund was initiated. A refund's status changed. ### Benefit grants A grant is one customer's access to one benefit — a license key, file download, Discord role, GitHub repo, or prepaid credits. These are your provisioning hooks. A benefit was granted to a customer — provision access. A grant changed. A benefit was revoked — tear down the access you provisioned. ## Organization events These track changes to your own catalog and account rather than a customer transaction — useful for keeping internal dashboards, caches, or read models in step with the dashboard and API. ### Benefits A benefit definition was created. A benefit definition changed. ### Products A product was created. A product's details or pricing changed. ### Organization Your organization's settings changed.