# Create a webhook

`POST https://api.rarebl.com/open/hooks/create`

Creates a webhook subscription. There are no accounts: the reply carries a management token and a signing secret, both shown once.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/create" -H "Content-Type: application/json" -d '{"type":"tx.confirmations","chain":"btc","url":"https://example.com/hooks/rarebl","txid":"9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db","confirmations":6}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | What to subscribe to. One of: block.new, tx.confirmations, address.activity, token.transfer. |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `url` | string | Yes | Your `https://` endpoint on port 443 or 8443. Private, loopback, link-local and reserved IPs are refused; redirects are not followed. |
| `txid` | string | No | `tx.confirmations`: the transaction to follow. |
| `address` | string | No | `address.activity` (and `token.transfer`): the address to follow. |
| `contract` | string | No | `token.transfer`: the token contract to follow (ETH, TRON). |
| `confirmations` | integer | No | Confirmation threshold for `tx.confirmations` and `address.activity`. 0 to 100 Default 6. |

## Responses

### API200 (HTTP 200): OK

The subscription. `manageToken` and `signingSecret` are shown once: store them now.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "manageToken": "mt_7c1d0e94a2b64f3880c5e1a9d27b6f40",
    "signingSecret": "whsec_b81f4a9c20de7536a1c4f08e93d2b715",
    "type": "tx.confirmations",
    "chain": "btc",
    "url": "https://example.com/hooks/rarebl",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "confirmations": 6,
    "status": "active",
    "createdAt": "2026-11-15T01:12:07Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | The subscription id. |
| `data.manageToken` | string | Authorizes every other hooks call (`X-Hook-Token`). Shown once. |
| `data.signingSecret` | string | Key of the `X-Rarebl-Signature` HMAC on every delivery. Shown once. |

### API400 (HTTP 400): Bad Request

The URL is not https on port 443 or 8443, or points to a private, loopback, link-local or reserved address.

```json
{
  "status": 0,
  "code": "API400",
  "message": "url must be an https URL on port 443 or 8443.",
  "data": {
    "param": "url"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Both secrets are returned once and cannot be shown again. Lose the token and you cannot manage the hook; lose the secret and you cannot verify deliveries (create a new subscription).
- Rate limit: 10 per minute, at most 100 active subscriptions per IP.
- In Try It, the `id` and token from this reply are saved in your browser and prefilled on the other webhook pages. **Reset saved Try It values** in the settings menu clears them.
- Events, signatures, retries and source IPs: [Webhooks](https://docs.rarebl.com/guides/webhooks). The reply carries `id`, `manageToken` and `signingSecret`, plus the subscription fields.