Templates

Templates let you customize the structure of webhook notifications you receive from Tatum.
You can choose between:

Legacy format - By Default this is the format used to ensure compatibility with existing users.
Enriched format - Recommended to use for most simple and ready to use format.
Enriched with Raw Data - Recommended to use if you need raw transactions data as well.
Custom templates (your own fields & naming)

Every template returns a templateId, which you can attach to any subscription to shape your webhook responses.

Enriched Format

A structured, human-friendly format with improved naming and embedded token metadata.

{
  "data": {
    "kind": "transfer",
    "blockHash": "0x1234567890abcdef...",
    "blockNumber": 18500000,
    "blockTimestamp": 1699123456,
    "txId": "0xabcdef1234567890...",
    "currency": "ETH",
    "txTimestamp": 1699123456,
    "from": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "to": "0x8ba1f109551bD432803012645Hac136c",
    "value": "1000000000000000000",
    "contractAddress": "0xA0b86a33E6441b8c4C8C0C8C0C8C0C8C0C8C0C8C",
    "tokenId": "12345",
    "logIndex": 2,
    "additionalData": {
      "gasUsed": "21000",
      "gasPrice": "20000000000"
    },
    "tokenMetadata": {
      "type": "nft",
      "decimals": 0,
      "symbol": "NFT",
      "name": "My NFT",
      "uri": "https://api.example.com/metadata/12345"
    },
    "subscriptionId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "subscriptionType": "ADDRESS_EVENT"
  },
  "location": "...",
  "scheme": "..."
}

Enriched with Raw Data Format

Includes everything from enriched format plus raw decoded log payloads under rawData.

{
  "data": {
    "kind": "transfer",
    "blockHash": "0x1234567890abcdef...",
    "blockNumber": 18500000,
    "blockTimestamp": 1699123456,
    "txId": "0xabcdef1234567890...",
    "currency": "ETH",
    "txTimestamp": 1699123456,
    "from": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "to": "0x8ba1f109551bD432803012645Hac136c",
    "value": "1000000000000000000",
    "contractAddress": "0xA0b86a33E6441b8c4C8C0C8C0C8C0C8C0C8C0C8C",
    "tokenId": "12345",
    "logIndex": 2,
    "additionalData": {
      "gasUsed": "21000",
      "gasPrice": "20000000000"
    },
    "tokenMetadata": {
      "type": "nft",
      "decimals": 0,
      "symbol": "NFT",
      "name": "My NFT",
      "uri": "https://api.example.com/metadata/12345"
    },
    "rawData": {
      "address": "0xA0b86a33E6441b8c4C8C0C8C0C8C0C8C0C8C0C8C",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x000000000000000000000000742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
        "0x0000000000000000000000008ba1f109551bD432803012645Hac136c"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000000000000000001"
    },
    "subscriptionId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "subscriptionType": "ADDRESS_EVENT"
  },
  "location": "...",
  "scheme": "..."
}

Field Mapping Overview

Mapping of important fields across formats:

Field	Enriched	Legacy	Custom
kind	✅ direct	❌	✅ if mapped
from / to	✅ direct	❌ → address / counterAddress	✅
value	✅ direct	❌ → amount	✅
tokenMetadata	✅ direct	❌ → asset / metadataURI	✅
rawData	✅	❌	✅
type	❌	✅ derived	✅
chain	outer field	inner field	configurable

Legacy Format (Default)

Legacy is the original webhook structure used across almost all notification types.

{
  // Common fields for all notification types
  "chain": "string",
  "blockNumber": 0,
  "txId": "string",
  "subscriptionType": "string",

  // The monitored address
  "address": "string",

  // The other party (may be null for mint/burn/internal)
  "counterAddress": "string or null",

  // Appears for all value-carrying events (native, internal, fungible, NFT, multitoken)
  "amount": "string",

  // Only for: NATIVE + INTERNAL + FUNGIBLE
  "currency": "string or null",

  // Only for ADDRESS_EVENT
  "asset": "string or null",

  // Only for: FUNGIBLE (ERC-20), NFT (ERC-721), MULTITOKEN (ERC-1155)
  "contractAddress": "string or null",

  // Only for NFT (ERC-721) and Multi-token (ERC-1155)
  "tokenId": "string or null",

  // Only for NFT (ERC-721) and Multi-token (ERC-1155)
  "metadataURI": "string or null",

  // Present only in mempool-supporting events
  "mempool": false
}

This format covers all types except:

The Legacy CONTRACT_ADDRESS_LOG_EVENT & FAILED_TXS_PER_BLOCK

CONTRACT_ADDRESS_LOG_EVENT (EVM Example)

{
  "events": [
    {
      "txId": "0xbcf42229dbd97a7c1554f0451a8d4ba6653593de06d4ea62691ce314d036d19e",
      "logIndex": 3,
      "timestamp": 1696945197000,
      "address": "0xeb0a4ee3cdfffe0ef29f967a34137dea3b529c89",
      "topic_0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "topic_1": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "topic_2": "0x000000000000000000000000cacdddf3c123b133cb36b0ee17925c7a70a1ea93",
      "topic_3": "0x0000000000000000000000000000000000000000000000000000000000000002",
      "data": "0x"
    }
  ],
  "blockNumber": 20312334,
  "chain": "celo-testnet",
  "subscriptionType": "CONTRACT_ADDRESS_LOG_EVENT"
}

CONTRACT_ADDRESS_LOG_EVENT (Tezos Example)

{
  "events": [
    {
      "txId": "op6Hu4iUV9bRxxGkc5qVexN1NXFYENpKEovyh41cC3W9a9voX2k",
      "tag": "swap",
      "payload": [
        { "int": "130" },
        { "int": "0" },
        { "int": "67034" },
        { "int": "118138" }
      ],
      "address": "KT1V5XKmeypanMS9pR65REpqmVejWBZURuuT"
    }
  ],
  "blockNumber": 4376363,
  "chain": "tezos-mainnet",
  "subscriptionType": "CONTRACT_ADDRESS_LOG_EVENT"
}

FAILED_TXS_PER_BLOCK

{
  "txId": "2rdy3YCZHSwvpWtuDom1d4Jjy5UU9STLxF3ffXau6GToReDkfw8wEgX541fvzvh6btVC5D8iNapcKTXfPsoDBk7A",
  "blockNumber": 110827114,
  "chain": "ethereum-mainnet"
}

Creating a Custom Template

Define your own structure using key mapping.

{
  "format": "json",
  "keys": {
    "whoSent": "from",
    "whomTo": "to",
    "howMuch": "value",
    "what": "currency"
  }
}

Response
templateId
Use this template ID during subscription creation to receive webhooks in your structure.

Using Templates in Subscriptions

{
  "type": "ADDRESS_EVENT",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x50747Ee6ad995E8234E251A35b90C0aFcBEe4d33",
    "url": "https://your.com/webhook-handler",
    "templateId": "YOUR_TEMPLATE_ID"
  }
}

Learn More

Create a Subscription: https://docs.tatum.io/reference/createsubscriptionv4
Templates API: https://docs.tatum.io/reference/createnotificationtemplate
Notifications Reference: https://docs.tatum.io/reference/notifications-reference