> ## 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 webhooks for [sponsored fee charges](/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.

<Note>
  Swap provider fee events are available for prepaid and postpaid accounts. Prepaid accounts receive
  an event after the charge is deducted from their credits. Gas sponsorship events currently support
  postpaid accounts. Support for prepaid accounts is coming soon.
</Note>

## Event types

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

## Subscribing

Swap provider fee charges use the `usage.swap_provider_fee.recorded` event type.

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.swap_provider_fee.recorded`.
</ResponseField>

<ResponseField name="event_id" type="string">
  A unique identifier for the usage event. Use it to deduplicate charge events.
</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",
    "event_id": "insert-gas-charge-event-id",
    "source_id": "wa_9f3c...7b",
    "source_type": "wallet-action-swap",
    "amount_usd": "0.004213",
    "recorded_at": 1722787200000
  }
  ```

  ```json usage.swap_provider_fee.recorded theme={"system"}
  {
    "type": "usage.swap_provider_fee.recorded",
    "event_id": "insert-swap-provider-sponsorship-event-id",
    "source_id": "wa_9f3c...7b",
    "source_type": "wallet-action-swap",
    "amount_usd": "0.750000",
    "recorded_at": 1722787200000
  }
  ```
</CodeGroup>

## Reconciling charges

A sponsored cross-chain transfer can report gas and routing costs as separate events. Both carry the same `source_id`, with different event types and `event_id` values.

Delivery is at least once, so the same event may arrive more than once. Use `event_id` to deduplicate charges and the `svix-id` header to identify a webhook 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="Swap provider fee charge recorded" icon="money-bill-transfer" href="/api-reference/webhooks/usage/swap_provider_fee_recorded" arrow>
    Full schema for `usage.swap_provider_fee.recorded`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.