Skip to main content
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 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. For the event model, delivery behavior, and signature verification, see the 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 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.
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.
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

​
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, the relay is confirmed → gateway.mint.forwarded
  3. The deposit is attested and tokens are minted on the destination blockchain → gateway.mint.finalized

​
Limits

ResourceLimit
Subscriptions per developer account20
Registered addresses per developer account50

​
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 account.

​
Get started

Webhook events reference

View schemas and examples for each event type