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

# Get started with Off the Hook

> Create your first TRON webhook subscription and receive a live transfer notification in four steps using the Off the Hook REST API.

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.

<Steps>
  <Step title="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.

    ```bash theme={null}
    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`:

    ```json theme={null}
    {
      "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"
    }
    ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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](https://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.
  </Step>

  <Step title="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](https://github.com/svix/svix-webhooks) works without modification.

    ```typescript theme={null}
    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](/guides/verify-signatures).
  </Step>
</Steps>

<Note>
  Now that you have a working subscription, you can add more addresses across Mainnet, Nile, and Shasta, explore event history in the [Events API](/api/events/list), or browse the full [API reference](/api/subscriptions/create) to manage subscriptions programmatically.
</Note>