Gateway webhook events

Reference for Gateway webhook event types, payload schemas, and example notifications.

Gateway sends webhooks for events on registered wallet addresses. All webhooks use the V2 notification format. The notificationType field names the event, and the notification field contains event data.

{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "notificationType": "gateway.deposit.finalized",
  "notification": {
    "...": "Event-specific data. Schema varies by notificationType."
  },
  "timestamp": "2026-04-22T12:00:00.000000000Z",
  "version": 2
}

Deposit events

gateway.deposit.finalized

Fires after tokens are deposited into a Gateway Wallet, the onchain transaction is finalized, and Gateway processes the deposit.

Payload fields

Field	Type	Description
id	string	Unique notification identifier
walletAddress	string	Registered wallet address that owns the funds.
domain	string	Chain domain identifier (for example, "0" for Ethereum)
env	string	Network environment: "testnet" or "mainnet"
tokenAddress	string	Token contract address
amount	string	Transfer amount in decimal format (for example, "1.000000" for 1 token)
from	string	Address that initiated the onchain deposit. May be the wallet owner or a delegate acting on their behalf.
to	string	Destination address
txHash	string	Onchain transaction hash

Example: gateway.deposit.finalized

{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "notificationType": "gateway.deposit.finalized",
  "notification": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "walletAddress": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "domain": "0",
    "env": "mainnet",
    "tokenAddress": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "amount": "1000.000000",
    "from": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "to": "0x19330d10d9cc8751218eaf51e8885d058642e08a",
    "txHash": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "timestamp": "2026-04-22T12:05:00.000000000Z",
  "version": 2
}

Mint events

The gateway.mint.finalized and gateway.mint.forwarded events share a payload schema. Mint event payloads include an attestations array. Each burn intent in a transfer maps to one attestation entry. A single transfer can include multiple burn intents, each with its own recipient and amount.

gateway.mint.finalized

Fires when an attestation is used and tokens are minted on the destination blockchain. The wasForwarded field shows whether the transfer used the forwarding service.

gateway.mint.forwarded

Fires when a forwarded mint relay is confirmed. This event only occurs for transfers that use the forwarding service.

Payload fields

Field	Type	Description
transferId	string	Transfer identifier (attestation group ID)
txHash	string	Onchain transaction hash on the destination blockchain
walletAddress	string	The depositor that owns the funds on the source chain
domain	string	Blockchain domain identifier for the destination blockchain (for example, "7" for Base)
env	string	Network environment: "testnet" or "mainnet"
tokenAddress	string	Token contract address on the destination blockchain
wasForwarded	boolean	Whether the transfer used the forwarding service (gateway.mint.finalized only)
attestations	array	Array of attestation details (see below)

Attestation fields

Field	Type	Description
from	string	The depositor address that triggered the burn on the source blockchain
to	string	Recipient address for this attestation
amount	string	Amount in decimal format (for example, "1.000000" for 1 token)
transferSpecHash	string	Transfer specification hash for this attestation

Example: gateway.mint.finalized

{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "f6a7b890-1234-5678-cdef-901234567890",
  "notificationType": "gateway.mint.finalized",
  "notification": {
    "transferId": "a7b89012-3456-7890-abcd-ef1234567890",
    "txHash": "0x1ea922932e2bbefab697b931aa423a6ebe4a683947a5bd105bb38958e52017a5",
    "walletAddress": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "domain": "7",
    "env": "mainnet",
    "tokenAddress": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "wasForwarded": false,
    "attestations": [
      {
        "from": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
        "to": "0x7777777700000000000000000000000000000001",
        "amount": "93516.491888",
        "transferSpecHash": "0x4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b"
      }
    ]
  },
  "timestamp": "2026-04-22T12:10:00.000000000Z",
  "version": 2
}

Example: gateway.mint.forwarded

This event fires only for transfers that use the forwarding service.

{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "notificationType": "gateway.mint.forwarded",
  "notification": {
    "transferId": "b8c90123-4567-8901-abcd-ef2345678901",
    "txHash": "0x2bc033043d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a",
    "walletAddress": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "domain": "3",
    "env": "mainnet",
    "tokenAddress": "0xcccccccccccccccccccccccccccccccccccccccc",
    "attestations": [
      {
        "from": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
        "to": "0x8888888800000000000000000000000000000002",
        "amount": "50000.000000",
        "transferSpecHash": "0x5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c"
      }
    ]
  },
  "timestamp": "2026-04-22T12:15:00.000000000Z",
  "version": 2
}