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

# Events catalog

> Events are grouped into categories. The tables below list the event key, description, and payload fields that appear under `event.data` in webhook requests.

### Paywall lifecycle

| Event            | Description             | Payload fields                                                       |
| ---------------- | ----------------------- | -------------------------------------------------------------------- |
| `updated`        | Settings changed.       | `paywallId`, `ownerUserId`, `changedFields`, `summarySections`       |
| `archived`       | Paywall archived.       | `paywallId`, `ownerUserId`, `reason`                                 |
| `secret.rotated` | API secret regenerated. | `paywallId`, `ownerUserId`, `secretLastFour`, `actorId`, `actorType` |

> Paywall creation does not emit a webhook because subscriptions can only be configured after a paywall exists.

### Integrations

| Event                                | Description                        | Payload fields                                                 |
| ------------------------------------ | ---------------------------------- | -------------------------------------------------------------- |
| `integration.connected`              | Integration enabled.               | `paywallId`, `ownerUserId`, `integrationKey`, `enabledBy`      |
| `integration.disconnected`           | Integration disabled.              | `paywallId`, `ownerUserId`, `integrationKey`, `disabledBy`     |
| `integration.stripe.webhook.rotated` | Stripe webhook endpoint recreated. | `paywallId`, `ownerUserId`, `webhookId`, `url`, `secretSuffix` |

### User authorization

| Event                     | Description                     | Payload fields                                                                                   |
| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `authorization.requested` | User approval required.         | `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`, `requestId`, `approvalUrl`, `mode` |
| `authorization.completed` | User connected successfully.    | `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`, `connectionId`                     |
| `authorization.revoked`   | Connection removed.             | `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`                                     |
| `authorization.declined`  | Authorization request declined. | `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`, `requestId`, `reason`              |

### Balances & funds

| Event                        | Description                  | Payload fields                                                                                             |
| ---------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `balance.deposit.created`    | Balance deposit recorded.    | `paywallId`, `ownerUserId`, `walletUserId`, `externalUserId`, `amount`, `currency`, `source`, `activityId` |
| `balance.topup.link.created` | Top-up checkout link issued. | `paywallId`, `ownerUserId`, `walletUserId`, `redirectUrl`, `checkoutSessionId`                             |
| `balance.trial.granted`      | Trial credits granted.       | `paywallId`, `ownerUserId`, `walletUserId`, `credits`, `activityId`                                        |

### Charges & usage

| Event                      | Description                                     | Payload fields                                                                                                |
| -------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `balance.charge.created`   | Manual or virtual charge recorded.              | `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `amount`, `processingFeeAmount`                     |
| `balance.charge.completed` | Charge marked as settled.                       | `paywallId`, `ownerUserId`, `activityId`, `settlementReference`                                               |
| `balance.charge.failed`    | Charge attempt failed.                          | `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `amount`, `errorCode`                               |
| `usage.charge.created`     | Usage-based charge computed.                    | `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `model`, `promptTokens`, `completionTokens`, `cost` |
| `usage.charge.deferred`    | Streaming charge deferred until usage is known. | `paywallId`, `ownerUserId`, `deferredRequestId`, `model`                                                      |
| `usage.rate.limited`       | Request hit usage rate limit.                   | `paywallId`, `ownerUserId`, `limit`, `date`, `model`, `walletUserId`                                          |
| `balance.depleted`         | Insufficient balance for a charge.              | `paywallId`, `ownerUserId`, `walletUserId`, `requestedAmount`, `availableBalance`                             |
| `request.blocked`          | Request blocked pre-provider.                   | `paywallId`, `ownerUserId`, `walletUserId`, `reason`, `requestId`                                             |

### Payments

| Event                               | Description                        | Payload fields                                                                        |
| ----------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------- |
| `stripe.checkout.session.completed` | Stripe Checkout session succeeded. | `paywallId`, `ownerUserId`, `checkoutSessionId`, `amount`, `currency`, `walletUserId` |

### Proxy events

| Event                     | Description                               | Payload fields                                                                |
| ------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
| `proxy.request.started`   | Proxy received a request.                 | `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`              |
| `proxy.request.completed` | Request completed successfully.           | `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`              |
| `proxy.request.failed`    | Request failed inside the proxy.          | `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`, `errorCode` |
| `proxy.request.canceled`  | Request was aborted before completion.    | `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`              |
| `proxy.request.blocked`   | Proxy blocked the request during routing. | `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `reason`             |

***