POST /v1/subscriptions

Use this endpoint to create a new subscription that delivers webhook events to your HTTPS endpoint. Once created, Off the Hook immediately begins matching on-chain activity against the subscription’s address filters and queues deliveries signed with the subscription’s secret. The secret is returned only in this response — store it somewhere safe before the request completes.

Request

POST /v1/subscriptions

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer oth_YOUR_API_KEY`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Unique string to make this request idempotent. Re-sending the same key returns the original response without creating a second subscription.

Body

object

required

Webhook delivery target. Only HTTPS is supported today; additional destination types (SQS, Pub/Sub) are planned.

Show destination properties

string

required

Must be "https". This is the only supported destination type in the current release.

string

required

The HTTPS URL Off the Hook will POST webhook events to. The URL must be publicly reachable and must not resolve to a private IP range (loopback, RFC 1918, link-local, etc.). Validation is performed at registration time and again on each delivery attempt.

string[]

required

One or more event kinds to subscribe to. Must be non-empty. Example: ["wallet.transfer.broadcasted"]. See Supported events for valid values.

string

default:"enabled"

Whether the subscription should immediately receive events. Accepted values: "enabled" or "disabled". Defaults to "enabled" when omitted.

string

A human-readable label for your own reference. Not interpreted by Off the Hook.

Supported events

Event kind	Status
`wallet.transfer.broadcasted`	Available
`service.ping`	Available (fired by `/test`)
`wallet.transfer.confirmed`	Planned
`wallet.transfer.failed`	Planned

Example request

curl -X POST https://api.offthehook.dev/v1/subscriptions \
  -H "Authorization: Bearer oth_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{
    "destination": {
      "type": "https",
      "url": "https://your-server.example.com/webhooks"
    },
    "events": ["wallet.transfer.broadcasted"],
    "status": "enabled",
    "description": "Production wallet monitor"
  }'

Response

201 Created

{
  "id": "sub_2QkP9aB7xN...",
  "destination": {
    "type": "https",
    "url": "https://your-server.example.com/webhooks",
    "secret": "whsec_..."
  },
  "events": ["wallet.transfer.broadcasted"],
  "filters": {
    "addresses": [],
    "hasMore": false
  },
  "status": "enabled",
  "description": "Production wallet monitor",
  "dateCreated": "2026-05-08T12:00:00Z",
  "dateUpdated": "2026-05-08T12:00:00Z"
}

The secret field is only returned when creating a subscription or rotating the secret. Store it immediately — subsequent GET requests will not include it.

Response fields

string

required

Unique subscription identifier. Always prefixed with sub_.

object

required

Webhook delivery target.

Show destination properties

string

required

Destination type. Currently always "https".

string

required

The HTTPS URL registered for this subscription.

string

The whsec_-prefixed signing secret used to produce webhook-signature headers. Only present in the create and secret-rotation responses. Pass this to a Standard Webhooks-compatible verification library.

string[]

required

The event kinds this subscription will receive.

object

required

Address filters attached to this subscription.

Show filters properties

object[]

Up to 200 inlined address filters. Each entry has chainId (CAIP-2 identifier, e.g. "tron:mainnet") and address (canonical base58check).

boolean

true when more than 200 address filters exist. Use GET /v1/subscriptions/:id/filters/addresses to paginate the full list.

string

required

"enabled" or "disabled".

string

required

The human-readable label supplied at creation time. Empty string if none was provided.

string

required

ISO 8601 timestamp of when the subscription was created.

string

required

ISO 8601 timestamp of the most recent update.

Errors

Code	Description
`invalid_request`	The request body is missing a required field, contains an invalid value, or the JSON is malformed.
`ssrf_blocked`	The `destination.url` resolved to a private or reserved IP range. The error detail includes the blocked IP and CIDR.
`unsupported_event`	One or more entries in `events` are not recognized. The error detail names the unsupported value.
`description_too_long`	The `description` field exceeds the maximum allowed length.
`idempotency_in_flight`	Another request with the same `Idempotency-Key` is still being processed. Wait and retry.
`idempotency_conflict`	A completed request with the same `Idempotency-Key` exists but had a different request body. Use a new key.
`unauthorized`	The `Authorization` header is missing or the API key is invalid.

Subscriptions

Address Filters

Events

Utilities

Request

Headers

Body

Supported events

Example request

Response

Response fields

Errors

​Request

​Headers

​Body

​Supported events

​Example request

​Response

​Response fields

​Errors

Request

Headers

Body

Supported events

Example request

Response

Response fields

Errors