Guides
SupportStatusSign UpLogin

v4 Notification Workflow

Suggest Edits

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.

Steps

Step_1: Create a 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

  1. 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
});
  1. Monitor Address: Tatum monitors the specified address for balance update events happening on the Ethereum blockchain.
  2. 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"
}

Updated 4 months ago