Get started with Off the Hook

This guide walks you through creating a subscription, adding a TRON address to watch, sending a test event, and verifying the signature on your end. By the end you will have a working end-to-end webhook pipeline with no on-chain activity required to test it.

Prerequisites

You need an Off the Hook API key. API keys are prefixed with oth_. Contact the Off the Hook team to provision your account.

Create a subscription

A subscription tells Off the Hook where to send events and which event types to deliver. Send a POST request to /v1/subscriptions with your destination URL and the events you want to receive.

curl -X POST https://api.offthehook.dev/v1/subscriptions \
  -H "Authorization: Bearer oth_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "type": "https", "url": "https://webhook.site/YOUR-ID" },
    "events": ["wallet.transfer.broadcasted"],
    "status": "enabled",
    "description": "My first subscription"
  }'

The response includes the subscription resource and a secret field under destination:

{
  "id": "sub_2QkP9aB7xN...",
  "destination": {
    "type": "https",
    "url": "https://webhook.site/YOUR-ID",
    "secret": "whsec_..."
  },
  "events": ["wallet.transfer.broadcasted"],
  "filters": { "addresses": [] },
  "status": "enabled",
  "description": "My first subscription",
  "dateCreated": "2026-05-08T12:00:00Z",
  "dateUpdated": "2026-05-08T12:00:00Z"
}

The secret field is returned only on creation and on secret rotation. Copy it now and store it securely — you cannot retrieve it again. You will need it to verify webhook signatures.

Add an address to watch

An empty subscription receives no events. Add a TRON address to your subscription’s address filter using a PATCH request. Replace sub_2QkP9aB7xN... with the ID from the previous step.

curl -X PATCH https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../filters/addresses \
  -H "Authorization: Bearer oth_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [
      { "chainId": "tron:mainnet", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" }
    ]
  }'

Each address entry includes a chainId using a CAIP-2 identifier. You can add addresses on multiple chains in a single request by including multiple objects in the add array.

Send a test event

You do not need to wait for a real on-chain transfer to verify your endpoint is working. The /test endpoint fires a service.ping event to your destination immediately.

curl -X POST https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../test \
  -H "Authorization: Bearer oth_YOUR_API_KEY"

Check your destination (for example, webhook.site) — you should see an incoming request within a few seconds. The payload will have "kind": "service.ping" and the same Standard Webhooks headers as a real transfer event, so you can use it to test your signature verification logic too.

Verify the webhook signature

Every delivery Off the Hook sends is signed with HMAC-SHA256. You must verify the signature before trusting the payload. Off the Hook implements the Standard Webhooks spec, so the Svix verification library works without modification.

import { Webhook } from "svix";

const wh = new Webhook(secret); // your "whsec_..." from step 1
const event = wh.verify(body, headers);

Pass the raw request body (not parsed JSON) and the full request headers. The library checks the webhook-signature, webhook-id, and webhook-timestamp headers. If verification fails, reject the request.For a complete example including replay attack prevention and deduplication, see Verify webhook signatures.

Now that you have a working subscription, you can add more addresses across Mainnet, Nile, and Shasta, explore event history in the Events API, or browse the full API reference to manage subscriptions programmatically.

Get Started

Core Concepts

Guides

Reference

Get started with Off the Hook

Prerequisites

​Prerequisites

Prerequisites