Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.offthehook.dev/llms.txt

Use this file to discover all available pages before exploring further.

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.
1

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.
2

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.
3

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.
4

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.