Workflow

Webhooks are automated messages sent from applications when certain events occur. The Tatum webhook system lets you receive notifications about balance update events for specific addresses.

👍
This Workflow is for Notifications v4

Steps

Step 1: Create a subscription

Use our Wizard to quickly set up your first notification subscription

In this example, we create a subscription type ADDRESS_EVENT

curl -i -X POST \
  https://api.tatum.io/v4/subscription?type=mainnet \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "ADDRESS_EVENT",
    "attr": {
      "address": "0xF64E82131BE01618487Da5142fc9d289cbb60E9d",
      "chain": "ETH",
      "url": "https://<YOUR_WEBHOOK_URL>"
    }
  }'

// yarn add @tatumio/tatum
import {TatumSDK, Network, Ethereum} from '@tatumio/tatum'

const tatum = await TatumSDK.init<Ethereum>({network: Network.ETHEREUM})

const subscription = await tatum.notification.subscribe.addressEvent({
  address: '0xF64E82131BE01618487Da5142fc9d289cbb60E9d', // replace with your address
  url: 'https://<YOUR_WEBHOOK_URL>' // replate with your URL handler
});

This function returns an object with an id property - a string identifier of the created subscription.

📘
Define the type of network
Playing with curl and having a need to define type of net, please, use query parameter type with testnet or mainnet values.
Example: https://api.tatum.io/v4/subscription?type=mainnet
If you do not use it explicitly mainnet is set by default.

Step 2: Monitor an address

Tatum starts monitoring the specified address for any balance update events happening on the blockchain.

Should you have specific access controls in place, you may want to whitelist Tatum IP addresses (TXT | JSON) that will fire requests to your application.

📘
Find additional Security suggestions in the following article.

Step 3: Triggering webhooks

Once Tatum detects an event, it fires a notification as an HTTP POST request to the webhook listener URL defined in the subscription. The request includes a JSON payload with the event details.

EVM Chains: One (1) confirmation is required to trigger the webhook
UTXO Chain: Two (2) confirmations are required to trigger the webhook

Step 4: Unsubscribe from the notification

The user can unsubscribe from the notification by calling tatum.notification.unsubscribe(id).

Step 5: List fired webhooks

Users can list all fired webhooks by calling the tatum.notification.getAllExecutedWebhooks() operation.

UML Diagram

Here's a UML diagram that focuses on the flow of subscribing, receiving events, and firing notifications. Code examples are included in the boxes for each step.

+------------------------+          +------------------------+
|                        |          |                        |
|   1. User Subscribes   |          |   2. Monitor Address   |
|                        |          |                        |
|   Code example:        |          |   (Handled by Tatum)   |
|                        |          |                        |
| tatum.notification     |          +-----------+------------+
|  .subscribe            |                      |
|  .addressEvent({       +--------------------->|
|   address: '0xF64E8...'|                      |
|   url: 'https://das...'|                      |
| });                    |                      |
+------------------------+                      |
                                                |
  +---------------------+                       |
  |                     |                       |
  |  Event Detected on  |<----------------------+
  |  the Address        +---------------------->|
  +---------------------+                       |
                                                |
                                                |
                                                |
                                                v
                                     +----------+----------+
                                     |                     |
                                     | 3. Process Event    |
                                     | (Tatum) &           |
                                     | Fire                |
                                     | Notification        |
                                     |                     |
                                     | (Handled by         |
                                     | Webhook             |
                                     | Listener)           |
                                     |                     |
                                     | Example             |
                                     | Payload:            |
                                     | {                   |
                                     |  "type": "BALANCE", |
                                     |  "amount": "0.5"    |
                                     | }                   |
                                     +---------------------+

Steps from diagram

Create subscription: The user creates a subscription using the TatumSDK with the specified address and webhook listener URL.

curl -i -X POST \
  https://api.tatum.io/v4/subscription?type=mainnet \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "ADDRESS_EVENT",
    "attr": {
      "address": "0xF64E82131BE01618487Da5142fc9d289cbb60E9d",
      "chain": "ETH",
      "url": "https://<YOUR_WEBHOOK_URL>"
    }
  }'

// yarn add @tatumio/tatum
import {TatumSDK, Network, Ethereum} from '@tatumio/tatum'

const tatum = TatumSDK.init<Ethereum>({network: Network.ETHEREUM})

const subscription = await tatum.notification.subscribe.addressEvent({
  address: '0xF64E82131BE01618487Da5142fc9d289cbb60E9d', // replace with your address
  url: 'https://<YOUR_WEBHOOK_URL>' // replate with your URL handler
});

Monitor Address: Tatum monitors the specified address for balance update events happening on the Ethereum blockchain.
Receive & Fire Notification: The webhook listener receives the event and processes the notification. An example JSON payload is provided in the diagram. Should you have specific access controls in place, you can whitelist these Tatum IP Addresses (TXT | JSON) that will fire requests to your application.

{
  "address": "0xF64E82131BE01618487Da5142fc9d289cbb60E9d",
  "amount": "0.001",
  "asset": "ETH",
  "blockNumber": 2913059,
  "counterAddress": "0x690B9A9E9aa1C9dB991C7721a92d351Db4FaC990",
  "txId": "0x062d236ccc044f68194a04008e98c3823271dc26160a4db9ae9303f9ecfc7bf6",
  "type": "native",
  "chain": "ethereum-mainnet",
  "subscriptionType": "ADDRESS_EVENT"
}

Advanced Configuration

Tatum Notifications support advanced configuration options that allow you to control when events are triggered and how they are formatted before being delivered to your webhook.

These options include:

⚠️
Advanced configuration are currently available only on TRON and EVM chains (V4).

Finality Levels

The finality parameter controls when a notification is dispatched relative to on-chain confirmation state.

Allowed values:

confirmed – Optimized for speed. The event is triggered once the transaction is confirmed on chain.
final – Waits for full block confirmation depth before dispatching the notification.

Use confirmed when lower latency is preferred.
Use final when you need higher settlement confidence (e.g., payment settlement or treasury operations).

👉 Refer to the Create Subscription V4 reference to see how to use this functionality.

Templates

Templates control the structure and formatting of webhook payloads. If no template is specified, notifications are delivered using the legacy format. Tatum also provides a default enriched template, which returns normalized, structured, and token-aware payloads. You can also create and manage custom templates to fully control the shape of your webhook data.

👉 See the Templates documentation for details on creating, updating, and managing notification templates.

Conditions

Conditions allow you to define additional rules that must be met before a notification is sent.
If the defined conditions are not satisfied, the event is not dispatched to your webhook.

Conditions support field-based comparisons such as transaction value, sender address, recipient address, contract address, or token attributes.

👉 Refer to the Create Subscription V4 reference for the full schema and supported fields.

Example

"conditions": [
  {
    "field": "value",
    "operator": ">=",
    "value": "1000000000000000000"
  }
]

Get API key For free. No commitment.

Don't have an API key?

Updated 8 days ago