Skip to main content

Flexible Webhook Quickstart

This example creates a webhook that tracks large USDC transfers (Whale Transfers) using the ERC-20 Transfer Stream on Ethereum Mainnet.

For an overview of Flexible Webhook concepts and key features, refer to Flexible Webhook Overview.

1. Set Up Your Environment​

1-1. Sign Up for Nodit Console​

If you are new to Nodit, visit the link below to sign up for the Nodit Console.


1-2. Get a Webhook Listener Endpoint​

You need a listener server to receive webhook notifications. In a real service you would build your own, but for this example we use a third-party service.

  • Postman Mockserver: Provides a temporary URL to receive webhook requests.

  • webhook.site: Capture and inspect webhook data in real time without a separate server. The free plan is limited to 50 incoming requests.

  • webhooktest.net: Capture and inspect webhook data without a separate server or account. No limit on incoming requests.

For this example, we use webhooktest.net. Visit webhooktest.net and copy the provided Webhook URL.


2. Create a Flexible Webhook​

2-1. Access the Webhook Menu​

After logging in to the Nodit Console, click Webhook in the left menu. Click the Flexible Webhook tab at the top. On the webhook list page, click the Create Webhook button.

Flexible Webhook is a console-only feature. Creation via API is not supported.


2-2. Enter General Information​

  1. Webhook Name: Enter a name to identify the webhook.
  2. Protocol: Select Ethereum.
  3. Network: Select Mainnet.
  4. Stream Type: Select ethereum.mainnet.erc20.transfer.
  5. Instant Webhook: Keep the default value (Off).

Enabling Instant Webhook delivers messages faster without waiting for block confirmation. However, data received may change if a chain reorganization (reorg) occurs. Off is recommended when data accuracy is important.


2-3. Set Conditions​

Selecting the USDC Whale Transfer Preset automatically sets the following conditions:

  • token_address == 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC contract)
  • value >= 1000000000000 (1,000,000 USDC, based on decimals 6)

In Visual Mode, you can add or modify conditions by drag-and-drop, or directly edit expressions in Text Mode.

Visual Mode and Text Mode can be switched at any time, and changes made in one mode are automatically reflected in the other. However, if you enter an expression in Text Mode that does not conform to the expected format, you cannot switch back to Visual Mode.



2-4. Select Output Fields​

Select which fields to include in the webhook payload. By default, all Receive Fields are selected. You can deselect unnecessary fields to reduce payload size.

Fields used in conditions (token_address, value) cannot be deselected.

In this example, select all fields:


2-5. Set the Webhook URL​

Paste the webhooktest.net URL you copied in step 1-2 into the Webhook URL field.


2-6. Live Testing​

You can validate your configuration before creating the webhook.

  • Live Sample: Preview recent real events that match the current conditions. Useful for verifying whether conditions are too narrow or too broad.
  • Test Webhook: Send a test payload to the configured endpoint and verify receipt and the response code.

Live Sample and Test Webhook use the latest data from the selected stream regardless of filtering conditions. The data may differ from what is actually received by the Webhook.


2-7. Complete Webhook Creation​

After confirming all settings, click the Create button to create the webhook. The created webhook will appear on the list page and is activated immediately.


3. Verify Webhook Reception​

When an on-chain event matching the conditions occurs, a message is sent to the endpoint. Check the received message on webhooktest.net.

Payload Structure​

All Flexible Webhook messages share the same envelope structure.

{
  "subscriptionId": "1234567890123456789",
  "sequenceNumber": 46,
  "streamId": "77",
  "streamSlug": "ethereum.mainnet.erc20.transfer",
  "data": {
    ...
  }
}

Field

Type

Description

subscriptionId

string

Unique ID of the webhook subscription

sequenceNumber

integer

Message sequence number. Increments sequentially within the same subscription

streamId

string

Unique ID of the stream

streamSlug

string

Stream identifier in `{protocol}.{network}.{streamType}` format

data

object

Event data that varies by stream type and selected fields


Sample Received Message​

Below is an example message matching the USDC Whale Transfer conditions.

{
  "subscriptionId": "1234567890123456789",
  "sequenceNumber": 46,
  "streamId": "77",
  "streamSlug": "ethereum.mainnet.erc20.transfer",
  "data": {
    "block_number": 19758850,
    "block_timestamp": 1714368119,
    "from_address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "to_address": "0x21a31ee1afc51d94c2efccaa2043afc4c2a23017",
    "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "value": "5000000000000",
    "transaction_hash": "0xef99067235b9d30831f5161cdfb9cd1a1b24f04fc9a694b120ef8e568bd70234"
  }
}

The fields under data vary depending on the stream type and output field configuration. Fields deselected during webhook creation will not be included.


4. Modify and Manage the Webhook​

Created webhooks can be modified and managed in the console.

4-1. Pause / Resume​

Click the Status toggle button to pause notifications. Click the toggle again to re-enable it.


4-2. Modify Conditions and Fields​

Conditions and fields cannot be changed after a webhook is created. If changes are needed, create a new webhook.


4-3. Resend Failed Messages with Easy Resend​

Select a FAILED message from the delivery history and click Resend to retransmit it. For more details, refer to Flexible Webhook Security & Reliability .


5. Delete a Webhook​

Click the trash icon Delete button on the webhook detail page or from the list to delete the webhook.


Deleted webhooks cannot be recovered. All settings and delivery history will be removed. Use Pause for a temporary stop.

Learn More​