Skip to main content

Webhooks REST API

Updated on
Jul 25, 2025

Overview​

The Webhooks REST API enables you to deploy and manage your Webhooks using a REST API interface.

Adding, updating, and managing your Webhooks is quick and easy!

Access​

To access the Webhooks REST API, you will first need to create an API key. Your API key should be set as an x-api-key header with your requests.

API Base URL: https://api.quicknode.com/

Supported Networks​

The Webhooks REST API is available on these chains and networks:

ChainMainnetTestnets
Abstract✅Testnet
Arbitrum✅Sepolia
Arbitrum Nova✅
Avalanche C-Chain✅Fuji
B3✅Sepolia
Base✅Sepolia
Bera✅Bepolia
Bitcoin✅
Blast✅Sepolia
BNB Smart Chain✅Testnet
Celo✅
Cyber✅Sepolia
Ethereum✅Holesky, Hoodi, Sepolia
Fantom✅
Flow✅Testnet
Fuse✅Ember Testnet
Gnosis✅
Gravity✅
Hedera✅Testnet
Hemi✅Testnet
Immutable zkEVM✅Testnet
Injective✅Testnet
Ink✅Sepolia
Japan Open Chain✅
Kaia✅Testnet
Lens✅Testnet
Linea✅
Mantle✅Sepolia
MonadComing SoonTestnet
Morph✅Holesky
Omni✅Omega
Optimism✅Sepolia
Peaq✅
PlasmaComing soonTestnet
Polygon✅Amoy
Polygon zkEVM✅Cardona Testnet
Race✅Testnet
Sahara✅Testnet
Scroll✅Testnet
Sei✅Testnet
Solana✅Devnet, Testnet
Soneium✅
Sophon✅Testnet
Story✅Aeneid Testnet
Tron✅
Unichain✅Sepolia
Vana✅Moksha Testnet
Worldchain✅Sepolia
Xai✅Sepolia
zkSync✅Sepolia
Zora✅
0g✅Galileo Testnet

API Endpoints​

The Webhooks REST API provides the following endpoints for managing your webhooks:

Creating Webhooks​

There are two ways to create webhooks:

  1. Create Webhook: Create a webhook with a custom filter function
  2. Create Webhook from Template: Create a webhook using predefined templates

Available Templates​

  • evmWalletFilter: Monitor specific EVM wallet addresses
  • evmContractEvents: Monitor specific contract events
  • solanaWalletFilter: Monitor specific Solana account addresses
  • bitcoinWalletFilter: Monitor specific Bitcoin wallet addresses
  • evmAbiFilter: Monitor contracts using ABI definitions

How to use templates: When creating a webhook from a template, the templateArgs object contains the template-specific properties directly. The template type is specified in the URL path (/webhooks/template/{id}), and the templateArgs contains the actual configuration data for that template.

Example: For the evmWalletFilter template, you would:

  • Use URL: /webhooks/template/evmWalletFilter
  • Include in body: "templateArgs": { "wallets": ["0x1234..."] }

Managing Webhooks​

Controlling Webhooks​

Testing​

  • Test Filter: Test your filtering logic before applying it

Authentication​

All API requests require authentication using your QuickNode API key. Include your API key in the request headers:

x-api-key: YOUR_API_KEY

Error Handling​

The API returns standard HTTP status codes:

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing API key

Webhook Configuration​

When creating or updating webhooks, you can configure the following parameters:

  • Name: A descriptive name for your webhook
  • Network: The blockchain network to monitor
  • Filter Function: JavaScript-based filtering logic (base64 encoded) - only for custom webhooks
  • Notification Email: Email address for termination notifications
  • Destination Attributes: Object containing:
    • URL: The endpoint where data will be sent
    • Security Token: Token for webhook authentication
    • Compression: Optional gzip compression for payloads
  • Status: Whether the webhook is active or paused
  • Template Args: Template-specific arguments (for template-based webhooks)

Template-Based Webhooks​

Template-based webhooks provide a simplified way to create common webhook configurations:

evmWalletFilter​

Monitor specific EVM wallet addresses:

{
  "templateArgs": {
    "wallets": ["0x1234...", "0x5678..."]
  }
}

evmContractEvents​

Monitor specific contract events:

{
  "templateArgs": {
    "contacts": ["0x1234..."],
    "eventHashes": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
  }
}

solanaWalletFilter​

Monitor specific Solana accounts:

{
  "templateArgs": {
    "accounts": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
  }
}

bitcoinWalletFilter​

Monitor specific Bitcoin wallet addresses:

{
  "templateArgs": {
    "addresses": ["bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"]
  }
}

evmAbiFilter​

Monitor contracts using ABI definitions:

{
  "templateArgs": {
    "abi": "[{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"name\":\"from\",\"type\":\"address\"}]}]",
    "contracts": ["0x1234..."]
  }
}

Filter Functions​

For custom webhooks, you can write JavaScript-based filtering functions that allow you to process and filter blockchain data before it's delivered to your endpoint. These functions are encoded in base64 and can be tested using the Test Filter endpoint.

For more information about writing filter functions, see the Filters documentation.

Webhook Delivery​

When a webhook is triggered, QuickNode sends a POST request to your specified URL with the filtered blockchain data. The payload includes:

  • data: The filtered blockchain events
  • metadata: Information about the webhook and delivery

Security​

The recommended way to secure your Webhook's destination endpoint is by implementing HMAC verification. This cryptographic method ensures that the incoming messages are coming from Webhooks and haven't been tampered with. For detailed information on implementing HMAC verification, see our guide on Validating Incoming Streams Webhook Messages.

IP Allowlisting (Additional Security)​

As an additional security measure, you can restrict access to your destination endpoint to specific IP addresses. Webhooks delivers data from the following IP address:

141.148.40.227

By adding this IP to your allowlist, you can add an extra layer of security to ensure that only legitimate Webhooks traffic is accepted by your webhook server.

Getting Help​

If you need assistance with the Webhooks REST API:

Last updated on
Share this doc