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

# Gateway webhooks

> Get Gateway event updates for your registered wallet addresses.

Use Gateway webhooks to get updates for your registered wallet addresses. Events
include Gateway Wallet deposits and mints on destination blockchains. Gateway is
fully permissionless, but webhook subscriptions require a free
[Circle Console](https://console.circle.com) account and API key. You do not
need billing or a credit card.

To set up an endpoint and subscribe, see
[Set up a webhook endpoint](/api-reference/webhook-endpoints). For the event
model, delivery behavior, and signature verification, see the
[Webhooks](/api-reference/webhooks) group in the API reference.

## Authentication

While Gateway itself is permissionless and does not require authentication,
webhook subscriptions require a Circle Console account and API key. Manage
subscriptions through the `POST /v2/notifications/subscriptions/permissionless`
endpoint. Create a free account at the
[Circle Console](https://console.circle.com) to get started. An API key is only
needed for managing webhook subscriptions, not for using Gateway's core transfer
features.

## Event types

Gateway webhooks currently support these event types:

* `gateway.deposit.finalized`: Tokens were deposited into a Gateway Wallet.
  Fires after the deposit transaction is finalized onchain and processed by
  Gateway.
* `gateway.mint.finalized`: Tokens were minted on the destination blockchain.
  Fires after the mint is finalized and processed by Gateway.
* `gateway.mint.forwarded`: A forwarded mint relay was confirmed. Fires only for
  forwarded transfers.

<Note>
  On instant-finality blockchains, the forwarded status moves directly from
  pending to finalized, skipping the confirmed state. Use a combination of
  `gateway.mint.finalized` and `gateway.mint.forwarded` to track the full
  transfer lifecycle across all blockchains.
</Note>

<Tip>
  Omit `notificationTypes` or use `gateway.*` to receive all Gateway event types,
  including any new types added in the future.

  * `gateway.*` (all types): the API returns `"restricted": false`
  * Subset of types: the API returns `"restricted": true`
</Tip>

### Example: deposit and mint lifecycle

The following example shows when events fire during a deposit and mint flow.

1. A user deposits tokens into a Gateway Wallet on a source blockchain →
   **`gateway.deposit.finalized`**
2. If the transfer uses the
   [forwarding service](/gateway/references/forwarding-service), the relay is
   confirmed → **`gateway.mint.forwarded`**
3. The deposit is attested and tokens are minted on the destination blockchain →
   **`gateway.mint.finalized`**

## Limits

| Resource                                   | Limit |
| ------------------------------------------ | ----- |
| Subscriptions per developer account        | 20    |
| Registered addresses per developer account | 50    |

## Environment

Gateway webhooks work with testnet and mainnet API keys. Use `TEST` for testnet.
Use `LIVE` for mainnet. You can create both from the same
[Circle Developer Console](https://console.circle.com) account.

## Get started

<Card title="Webhook events reference" icon="book" href="/gateway/references/webhook-events">
  View schemas and examples for each event type
</Card>