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

# Usage webhooks

> Receive an event each time Privy records a usage charge, and reconcile it against a wallet action

Privy publishes a webhook each time it records a [metered usage charge](/wallets/gas-and-asset-management/usage-billing/overview). Each event carries the amount and the wallet action that incurred it, so an app can attribute costs to users and flows without waiting for the monthly invoice.

<Note>
  Only accounts on postpaid billing receive these events. Contact
  [sales@privy.io](mailto:sales@privy.io) to enable postpaid billing for an account.
</Note>

## Event types

| Event name                       | Type                             | Action                                                      |
| -------------------------------- | -------------------------------- | ----------------------------------------------------------- |
| Gas sponsorship charge recorded  | `usage.gas_sponsorship.recorded` | Privy recorded a charge for sponsored network gas.          |
| Cross-chain swap charge recorded | `usage.cross_chain_fee.recorded` | Privy recorded a charge for a cross-chain transfer or swap. |

## Subscribing

In the Privy Dashboard, go to the **Configuration > Webhooks** page and select the events under **Usage charges**. Both events require the wallet API to be enabled for the app, since usage arises from wallet action traffic.

<Info>
  See the [webhooks overview](/api-reference/webhooks/overview) for registering an endpoint and
  verifying payload signatures.
</Info>

## Payload

Both events share the same payload.

<ResponseField name="type" type="string">
  The event type — either `usage.gas_sponsorship.recorded` or `usage.cross_chain_fee.recorded`.
</ResponseField>

<ResponseField name="source_id" type="string">
  The ID of the wallet action that incurred the charge. Use this to look up the action and reconcile
  the charge.
</ResponseField>

<ResponseField name="source_type" type="'wallet-action-transfer' | 'wallet-action-swap'">
  The type of wallet action that incurred the charge.
</ResponseField>

<ResponseField name="amount_usd" type="string">
  The charge amount in USD, as a decimal string with six decimal places (e.g. `"0.004213"`). A
  charge smaller than a cent keeps its exact value rather than rounding, so charges total accurately
  across a billing period.
</ResponseField>

<ResponseField name="recorded_at" type="number">
  When Privy recorded the charge, in milliseconds since the Unix epoch.
</ResponseField>

## Examples

<CodeGroup>
  ```json usage.gas_sponsorship.recorded theme={"system"}
  {
    "type": "usage.gas_sponsorship.recorded",
    "source_id": "wa_9f3c...7b",
    "source_type": "wallet-action-swap",
    "amount_usd": "0.004213",
    "recorded_at": 1722787200000
  }
  ```

  ```json usage.cross_chain_fee.recorded theme={"system"}
  {
    "type": "usage.cross_chain_fee.recorded",
    "source_id": "wa_9f3c...7b",
    "source_type": "wallet-action-swap",
    "amount_usd": "0.750000",
    "recorded_at": 1722787200000
  }
  ```
</CodeGroup>

## Reconciling charges

One wallet action can emit two charges of different types. A sponsored cross-chain transfer reports its gas and its routing cost as separate events, both carrying the same `source_id`.

Delivery is at least once, so the same event may also arrive more than once. The payload carries no idempotency key, so use the `svix-id` header to identify a redelivery.

<Info>
  See [webhook delivery](/api-reference/webhooks/overview#webhook-delivery) for the retry schedule.
</Info>

## API reference

<CardGroup cols={2}>
  <Card title="Gas sponsorship charge recorded" icon="gas-pump" href="/api-reference/webhooks/usage/gas_sponsorship_recorded" arrow>
    Full schema for `usage.gas_sponsorship.recorded`.
  </Card>

  <Card title="Cross-chain swap charge recorded" icon="money-bill-transfer" href="/api-reference/webhooks/usage/cross_chain_fee_recorded" arrow>
    Full schema for `usage.cross_chain_fee.recorded`.
  </Card>
</CardGroup>