Webhook Events and Payload Structure

Every webhook delivery from Off the Hook is a Standard Webhooks-compliant HTTP POST to your destination URL. The body is a JSON envelope with a consistent shape across all event types: a unique event ID, a kind string that identifies what happened, a timestamp, and a data object containing the chain-specific transfer details. Your endpoint can use these fields to identify the event, verify it hasn’t been processed before, and extract the transfer information you need.

Payload structure

{
  "id": "evt_8xN9kP2QbA...",
  "kind": "wallet.transfer.broadcasted",
  "date": "2026-05-08T12:34:56Z",
  "data": {
    "chainId": "tron:mainnet",
    "blockNumber": 78912345,
    "blockHash": "00000000...",
    "blockTimestamp": 1730000000000,
    "txId": "abc123...",
    "logIndex": 0,
    "from": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy",
    "to": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1500000000",
    "asset": {
      "type": "fungible",
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "symbol": "USDT",
      "decimals": 6
    },
    "matchedAddresses": [
      {
        "chainId": "tron:mainnet",
        "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy",
        "role": "from"
      }
    ]
  }
}

Envelope fields

string

required

Unique event identifier, prefixed evt_. This ID is stable across retries — if Off the Hook retries a failed delivery, the same id appears in every attempt. Use it as your idempotency key to avoid processing the same transfer twice.

string

required

The event type string, such as "wallet.transfer.broadcasted". Your subscription only receives events whose kinds appear in its events array. See event types for all supported values.

string

required

ISO 8601 timestamp of when the event was generated.

Transfer data fields

string

required

CAIP-2 chain identifier for the network where the transfer occurred, such as "tron:mainnet". See supported networks.

number

required

The block number that included this transfer.

string

required

The hash of the block that included this transfer.

number

required

Unix timestamp of the block in milliseconds.

string

required

The TRON transaction ID.

number

required

Position of this transfer within the block. For TRC-20 tokens this is the index of the Transfer log event (0-based). For native TRX transfers this is always -1 — a deliberate sentinel that avoids colliding with the first TRC-20 log in the same transaction.

string

required

Sender address in canonical TRON base58check format (starts with T).

string

required

Recipient address in canonical TRON base58check format.

string

required

Raw integer transfer amount as a string. Divide by 10^asset.decimals to get the human-readable value. For example, "1500000000" with decimals: 6 is 1,500 USDT.

object

required

Describes the transferred token.

Show asset fields

string

required

"native" for TRX, or "fungible" for TRC-20 tokens.

string | null

required

Contract address for TRC-20 tokens. null for native TRX.

string | null

Token symbol, such as "USDT". May be null for TRC-20 contracts whose metadata Off the Hook has not indexed yet — in that case read the raw amount directly.

number | null

Decimal precision of the token. May be null for unknown TRC-20 contracts.

object[]

required

The addresses from your subscription’s filter list that caused this event to fire. Each entry includes the chain, the address, and the role it played in the transfer: "from" if the address sent the funds, or "to" if it received them. A single transfer can match the same address in both roles if your filter includes both sender and recipient.

Deduplication

Off the Hook retries deliveries on 5xx, 408, 429, and network errors using a backoff schedule of 200ms, 1s, 5s, 1min, 5min, 30min, and 2h. Every attempt — original and retries — carries the same webhook-id header, which matches the id field in the payload body. To avoid processing the same transfer twice, record the webhook-id of every delivery you successfully handle and skip any delivery whose ID you’ve already seen.

app.post('/webhooks', async (req, res) => {
  const eventId = req.headers['webhook-id'];

  if (await db.eventAlreadyProcessed(eventId)) {
    return res.status(200).send('already processed');
  }

  // handle the event
  await processTransfer(req.body);
  await db.markEventProcessed(eventId);

  res.status(200).send('ok');
});

Delivery headers

Each POST request Off the Hook sends includes the following headers:

Header	Value
`content-type`	`application/json`
`webhook-id`	Event ID (e.g. `evt_8xN9kP2QbA...`)
`webhook-timestamp`	Unix timestamp (seconds)
`webhook-signature`	`v1,<base64-hmac-sha256>`
`x-oth-subscription-id`	Your subscription ID
`user-agent`	`OffTheHook/0.1`

During a secret rotation grace window, the webhook-signature header contains multiple v1, values separated by spaces — one for each active secret. A valid signature from any of them means the delivery is authentic.

Next steps

Event types — full catalog of supported event kinds
Verifying signatures — how to validate the HMAC signature on each delivery

Get Started

Core Concepts

Guides

Reference

Webhook Events and Payload Structure

Payload structure

Envelope fields

Transfer data fields

Deduplication

Delivery headers

Next steps

​Payload structure

​Envelope fields

​Transfer data fields

​Deduplication

​Delivery headers

​Next steps

Payload structure

Envelope fields

Transfer data fields

Deduplication

Delivery headers

Next steps