> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks API

> REST reference for Coinversa Pulse webhooks at webhook.coinversa.ai — Bearer auth, GET /v1/subscriptions/definitions, POST /v1/subscriptions with deliveryMode http or inbox, args.user as one address or an array of up to 1,000, the cohort bias args and the args of the four liquidation risk types, list, delete one or all, re-enable, read the signing secret, the inbox state, drain and ack routes, the unauthenticated health route, and the 400, 401, 403, 413, 429 and 503 errors.

Every route on this page is relative to one base URL and, except `/health`, authenticated:

```text theme={null}
https://webhook.coinversa.ai
Authorization: Bearer YOUR_API_KEY
```

Subscriptions belong to the **account**, not to a particular key: any of your keys sees and manages all of them, and they share one allowance and one [inbox](https://docs.coinversa.ai/webhooks/inbox.md). The same operations are in the developer portal's **Webhooks** page and, for inbox subscriptions and reading the inbox, in the [MCP tools](https://docs.coinversa.ai/webhooks/agents.md#the-tools).

> [!NOTE]
>
> This API is served by `webhook.coinversa.ai`, not the data API at `api.coinversa.ai`. It takes `Authorization: Bearer`, not `X-API-Key`, and it is not in the data API's OpenAPI spec. REST auth failures are `403` on the data API; here a missing or invalid key is `401`.

## Authentication

One header, the same key as REST and the WebSocket:

```text theme={null}
Authorization: Bearer <cvsa_ API key>
```

Subscriptions and the inbox belong to the account, not to one key: sibling keys on the same account see and manage the same subscriptions and share the allowance. Connections made through the hosted MCP connector are authenticated for you; nothing to configure.

Missing or invalid credentials, and unknown, revoked or suspended keys, are `401`. An auth-backend outage is `503`, never anonymous access — treat a `503` as *temporarily unavailable* and retry, not as a bad key.

## Summary

Every authenticated row takes the Bearer header above.

| Method | Path | Auth | What it does |
| - | - | - | - |
| `GET` | `/v1/subscriptions/definitions` | yes | The types your plan may create, with `args`, `filters` and `minTier` |
| `POST` | `/v1/subscriptions` | yes | Create a subscription with `deliveryMode` `http` (default, returns the signing secret) or `inbox` (no `url`, no secret) |
| `GET` | `/v1/subscriptions` | yes | List this account's subscriptions with their `deliveryMode` (no secrets) |
| `DELETE` | `/v1/subscriptions` | yes | Delete **all** this account's subscriptions |
| `DELETE` | `/v1/subscriptions/{id}` | yes | Delete one subscription |
| `POST` | `/v1/subscriptions/{id}/enable` | yes | Re-enable a subscription a `410` disabled |
| `GET` | `/v1/subscriptions/{id}/secret` | yes | Read the subscription's signing secret (`400` on an inbox subscription) |
| `GET` | `/v1/inbox` | yes | The account inbox's `state` |
| `POST` | `/v1/inbox/drain` | yes | Read up to `count` pending inbox messages within `maxBytes`, oldest first, without deleting them |
| `POST` | `/v1/inbox/ack` | yes | Delete inbox messages by batch prefix or by `inboxIds` |
| `GET` | `/health` | none | Liveness: `200`, with service counts in the body |

## Definitions

`GET /v1/subscriptions/definitions` → `{ "types": [...], "filterLogic": "and" }`.

Only the types **permitted by your tier** are listed, so Free sees the Free-tier types even though its subscription allowance is zero: feed access and subscription allowance are separate checks. The same declarations drive validation and event field extraction — this is not an arbitrary query interface. Each type carries:

| Field | Meaning |
| - | - |
| `type` | The name you send at creation |
| `args` | Scope and configuration arguments. Each declares `type`, `required`, optional `options` and optional `default`. Wallet arguments also declare `minItems: 1` and `maxItems: 1000`: they take one address or an array — or `maxItems: 1` on the two wallet [liquidation risk types](#liquidation-risk-types), which take exactly one. Three arguments also declare a numeric range: `max` on `priceMovePct`, and `min` and `max` on the integer arguments `buckets` and `range`, which are sent as strings like every other number. Other ranges, such as `points` on `cohortBiasMove`, are enforced at creation without being declared |
| `filters` | Public field names. Each declares `type`, `label`, optional `unit` (`base`, `quote`, `minutes`, `ratio`, `count` or `percent`), `exact`, optional enum `options` and the allowed numeric `operators` |
| `minTier` | The minimum plan, inherited from the underlying feed. `priceCross` also exports `sourceMinTiers` for its `mark` and `trade` sources |

```json theme={null}
{
  "type": "tradesByUser",
  "args": {"user": {"type": "address", "required": true, "minItems": 1, "maxItems": 1000}},
  "filters": {
    "coin": {"type": "string", "label": "Market", "exact": true},
    "sz": {
      "type": "decimal", "label": "Size", "unit": "base",
      "exact": true, "operators": ["gt", "gte", "lt", "lte"]
    }
  },
  "minTier": "free"
}
```

The example omits the other trade fields for brevity. `minItems` and `maxItems` on `user` mean it accepts one address or an array of 1 to 1,000 ([one wallet or many](#one-wallet-or-many)). Read the endpoint rather than maintaining a client-side list.

## Create a subscription

`POST /v1/subscriptions`

| Body field | Type | Required | Notes |
| - | - | - | - |
| `type` | string | yes | A [subscription type](https://docs.coinversa.ai/webhooks/events.md): one of the six event types, the four [cohort bias types](https://docs.coinversa.ai/webhooks/cohort-bias.md) or the four [liquidation risk types](https://docs.coinversa.ai/webhooks/liquidation-types.md) |
| `args` | object | per type | `user` for the four by-user types — one address or an array of 1 to 1,000 ([below](#one-wallet-or-many)); `coin`, `threshold`, optional `source` and `direction` for `priceCross`; none for `liquidations`; `coin` and, per type, `cohort`, `otherCohort`, `points`, `direction` and `tierType` for the cohort bias types ([below](#cohort-bias-types)); one `user` or a `coin`, with a threshold, for the liquidation risk types ([below](#liquidation-risk-types)). Wallets are normalised to lowercase |
| `filters` | object | no | Exact values or `gt` / `gte` / `lt` / `lte` bounds, AND across fields — see [Filters](https://docs.coinversa.ai/webhooks/events.md#filters). `priceCross`, `cohortBiasOpposition`, `liquidationRiskCross`, `liquidationExposure` and `liquidationMap` take none |
| `deliveryMode` | string | no | `http` (default) delivers to `url`; `inbox` stores matches in the account [inbox](https://docs.coinversa.ai/webhooks/inbox.md) instead |
| `url` | string | for `http` | Public HTTPS on port 443. Redirects and private or reserved addresses are refused. **Omit it** on an inbox subscription |

```json theme={null}
{
  "type": "tradesByUser",
  "args": {"user": "0x0123456789012345678901234567890123456789"},
  "filters": {"coin": "BTC", "sz": {"gt": "1.5", "lte": "10"}},
  "url": "https://example.com/hook"
}
```

`args` selects and configures the source independently of the optional `filters`. The original top-level `user` spelling is still accepted, but do not send `user` both at the top level and inside `args`.

### One wallet or many

On the four by-user types `args.user` is **one address string or an array of 1 to 1,000 addresses**; the definitions advertise `minItems: 1` and `maxItems: 1000` on the argument. The top-level `user` spelling accepts either form too.

```json theme={null}
{
  "type": "tradesByUser",
  "args": {
    "user": [
      "0x0123456789012345678901234567890123456789",
      "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]
  },
  "filters": {"coin": "BTC", "sz": {"gt": "1.5", "lte": "10"}},
  "url": "https://example.com/hook"
}
```

* One array is **one subscription** against your allowance and one underlying processor feed; it does not change the type's minimum plan.
* Addresses are lowercased; arrays are **sorted and deduplicated**. The 1,000 limit is checked before deduplication.
* An **empty array**, an **invalid address** or **more than 1,000 entries** is a `400`. Creation bodies are limited to **64 KiB**.
* In create and list responses a one-element array — including one left after deduplication — is returned as a **string**; the legacy top-level `user` appears only for a single-wallet scope.
* Matching events from every listed wallet in a source block arrive together, in source order, in one delivery's `data`, with the same filters applied to each. Non-wallet arguments stay single-valued.

### Cohort bias types

The four cohort bias types take `coin` and, depending on the type, a cohort, a second cohort, a direction or a number of points. One body per type, with every required argument:

```json theme={null}
{"type": "cohortBias", "args": {"coin": "BTC"}, "url": "https://example.com/hook"}
```

```json theme={null}
{"type": "cohortBiasFlip", "args": {"coin": "BTC", "cohort": "apex", "direction": "short"}, "url": "https://example.com/hook"}
```

```json theme={null}
{"type": "cohortBiasOpposition", "args": {"coin": "BTC", "cohort": "apex", "otherCohort": "crowd"}, "url": "https://example.com/hook"}
```

```json theme={null}
{"type": "cohortBiasMove", "args": {"coin": "BTC", "cohort": "apex", "points": "10"}, "url": "https://example.com/hook"}
```

* `coin` is required on all four, matched case-insensitively, and can be a qualified symbol such as `xyz:GOLD`.
* `tierType` is optional on all four: `pnl` (default), `size`, `pnl_recent` or `size_recent`. A `cohort` or `otherCohort` must belong to that classification — a cohort from the other one is a `400` — and `cohortBiasOpposition` needs two different cohorts.
* `direction` on `cohortBiasFlip` is `long`, `short` or `both` (default): the side the cohort flips to.
* `points` on `cohortBiasMove` is a positive decimal **string**, at most `200`: percentage points of net bias.
* `cohortBias`, `cohortBiasFlip` and `cohortBiasMove` accept the `netBias`, `longNotional`, `shortNotional` and `accountCount` filters; `cohortBiasOpposition` accepts none.

They are evaluated on stored snapshots, normally taken every 15 minutes, not on each trade. What each one fires on, the cohorts and the delivered rows are on [Cohort bias types](https://docs.coinversa.ai/webhooks/cohort-bias.md).

### Liquidation risk types

The four liquidation risk types take either one wallet or one market, and a threshold. One body per type, with every required argument:

```json theme={null}
{"type": "liquidationRiskCross", "args": {"user": "0x0123456789012345678901234567890123456789", "liquidationDistancePct": "5", "direction": "below"}, "url": "https://example.com/hook"}
```

```json theme={null}
{"type": "liquidationRisk", "args": {"user": "0x0123456789012345678901234567890123456789", "points": "2"}, "url": "https://example.com/hook"}
```

```json theme={null}
{"type": "liquidationExposure", "args": {"coin": "BTC", "priceMovePct": "3", "minNotional": "6000000"}, "url": "https://example.com/hook"}
```

```json theme={null}
{"type": "liquidationMap", "args": {"coin": "BTC", "priceChangePct": "1"}, "url": "https://example.com/hook"}
```

* `user` on `liquidationRiskCross` and `liquidationRisk` is **exactly one** wallet — a string or a one-element array. A second address is a `400`. There is no `coin` argument: every open position on record for the wallet is checked.
* `liquidationDistancePct` on `liquidationRiskCross` is a positive decimal **string** in percent (`"5"` is 5%); `direction` is `above`, `below` or `both` (default), and `below` is closer to liquidation.
* `points` on `liquidationRisk` is a positive decimal string — percentage points of distance, with no upper limit. It is the one type of the four that takes a filter: `liquidationDistancePct`.
* `coin` on `liquidationExposure` and `liquidationMap` is matched case-insensitively and can be a qualified symbol such as `xyz:GOLD`.
* `priceMovePct` on `liquidationExposure` is a decimal string above `0` and at most `100`; `minNotional` is a positive decimal string in quote units. `direction` is `down`, `up` or `both` (default). `resetNotional` is optional, positive and at most `minNotional`, and defaults to it.
* `priceChangePct` on `liquidationMap` is a positive decimal string. `buckets` and `range` are optional **integer strings**: `"1"` to `"200"` (default `"50"`) and `"1"` to `"100"` (default `"30"`).

They are evaluated about once a minute on stored positions and liquidation levels, not on each price tick. What each one fires on and the delivered fields are on [Liquidation risk types](https://docs.coinversa.ai/webhooks/liquidation-types.md).

The response carries the subscription — `type`, the normalised `args`, the saved `filters`, its `id`, `deliveryMode`, `url` and `disabled` status — and, **on creation of an `http` subscription only**, the `whsec_…` signing secret. List responses never include it; read it later with [`GET /v1/subscriptions/{id}/secret`](#read-the-signing-secret).

### Inbox delivery

Send `"deliveryMode": "inbox"` and no `url`, and matching frames are stored in your account's one inbox instead of being POSTed — the same types, `args` and `filters`, one of the same subscription slots, no signing secret, and `403` on Free. Read them with the three inbox routes [below](#inbox). The full contract is on [Inbox delivery](https://docs.coinversa.ai/webhooks/inbox.md).

```json theme={null}
{
  "type": "tradesByUser",
  "args": {"user": "0x0123456789012345678901234567890123456789"},
  "filters": {"coin": "BTC"},
  "deliveryMode": "inbox"
}
```

A subscription's configuration is **immutable**: delete and recreate to change it, which also resets `priceCross` crossing state and a cohort bias or liquidation risk subscription's state. If activating the underlying feed fails, creation **rolls back** and answers `503` rather than leaving a saved subscription behind.

Errors: `400` (invalid format, unknown type, argument, filter or operator, impossible range, an empty or over-1,000 `user` array or an invalid address in it, a cohort outside the chosen `tierType`, `points` outside its range, more than one wallet on a liquidation risk type, `priceMovePct` above `100`, `resetNotional` above `minNotional`, `buckets` or `range` that is not an integer string in its range, a body over 64 KiB — checked before anything is saved), `403` (the type is not permitted by your tier, or an inbox subscription on Free), `429` (your account is at its subscription allowance), `503` (auth, storage or feed unavailable).

| Type | `args` | Minimum plan |
| - | - | - |
| `tradesByUser` | required `user`: one address or 1–1,000 | Free (Free's allowance is zero) |
| `twapSliceFillsByUser` | required `user`: one address or 1–1,000 | Free (Free's allowance is zero) |
| `twapStatusesByUser` | required `user`: one address or 1–1,000 | Pro |
| `liquidations` | none | Agent |
| `liquidationsByUser` | required `user`: one address or 1–1,000 | Agent |
| `priceCross` | required `coin`, `threshold`; optional `source`, `direction` | Free for both sources (Free's allowance is zero) |
| `cohortBias` | required `coin`; optional `cohort`, `tierType` | Starter |
| `cohortBiasFlip` | required `coin`, `cohort`; optional `direction`, `tierType` | Starter |
| `cohortBiasOpposition` | required `coin`, `cohort`, `otherCohort`; optional `tierType` | Starter |
| `cohortBiasMove` | required `coin`, `cohort`, `points`; optional `tierType` | Starter |
| `liquidationRiskCross` | required `user` (exactly one wallet), `liquidationDistancePct`; optional `direction` | Starter |
| `liquidationRisk` | required `user` (exactly one wallet), `points` | Starter |
| `liquidationExposure` | required `coin`, `priceMovePct` (above `0`, at most `100`), `minNotional`; optional `direction`, `resetNotional` (at most `minNotional`) | Starter |
| `liquidationMap` | required `coin`, `priceChangePct`; optional `buckets` (integer string, `1`–`200`, default `50`), `range` (integer string, `1`–`100`, default `30`) | Starter |

Tier checks are **creation-time** checks, not continuous re-authorisation of saved subscriptions after an account change.

## List subscriptions

`GET /v1/subscriptions` → this account's subscriptions, each with its `type`, `args`, `filters`, `id`, `deliveryMode` (`"http"` or `"inbox"`), `url` (HTTP subscriptions) and `disabled` status. No secrets.

## Delete a subscription

`DELETE /v1/subscriptions/{id}` deletes one subscription you own. For `priceCross`, the cohort bias types and the liquidation risk types it also removes the stored baseline or state and any pending deliveries in the outbox. Deleting an inbox subscription stops collection but **does not delete the messages it already stored** — acknowledge those on the [inbox](https://docs.coinversa.ai/webhooks/inbox.md#acknowledge).

## Delete all subscriptions

`DELETE /v1/subscriptions` deletes every subscription on the account.

## Re-enable a subscription

`POST /v1/subscriptions/{id}/enable` re-enables a subscription that a `410` from your URL disabled. It is idempotent. It answers `429` if the account is already at its subscription allowance — a disabled subscription does not count toward it, so enabling one is a creation-time check again.

## Read the signing secret

`GET /v1/subscriptions/{id}/secret` returns the subscription's `whsec_…` signing secret — the one returned at creation. There is one secret per subscription and no rotation; see [Signatures and delivery](https://docs.coinversa.ai/webhooks/signatures.md#one-secret-per-subscription). An **inbox** subscription has no secret, and this route answers `400` for it.

## Inbox

Three routes read the account's one inbox; the semantics are on [Inbox delivery](https://docs.coinversa.ai/webhooks/inbox.md).

| Route | Request | Response |
| - | - | - |
| `GET /v1/inbox` | — | `{"state": {pendingMessages, pendingBytes, maxMessages, maxStoredBytes, overflowDroppedTotal, expiredTotal}}` |
| `POST /v1/inbox/drain?count=10&maxBytes=65536` | No body. `count` 1–1,000 (default 10); `maxBytes` 1,024–4,194,304 (default 65,536), a budget for the whole response | `{"batchId", "messages", "hasMore", "state"}` — oldest first, **nothing deleted**. `413` with `requiredMaxBytes` when the oldest message does not fit; an empty inbox returns an empty `batchId` |
| `POST /v1/inbox/ack` | **One** of `{"batchId", "count"}` (an absolute prefix of that batch) or `{"inboxIds": [...]}` (1–1,000) | `{"acknowledged", "state"}` — `acknowledged` is what **this** request removed, so a retry returns `0`. Idempotent |

A message is the delivery envelope plus `inboxId` (`msg_` + 32 hex) and `receivedAt` ([the message](https://docs.coinversa.ai/webhooks/inbox.md#the-message)).

## Health

`GET /health` needs **no key** and answers `200` while the service is up. The body is a JSON object of counts — `subscriptions` (saved subscriptions), `feeds` (active feed subscriptions), `queued` (fresh deliveries waiting), `retrying` (retries waiting) and `outbox` (pending outbox rows). Treat the status code as the health signal and the body as informative: a build may answer `200` with an empty body, so accept both. It does not check auth or feed readiness.

## Delivery semantics

What a delivery looks like is on [Signatures and delivery](https://docs.coinversa.ai/webhooks/signatures.md). The status codes **your** URL returns mean:

| Your response | Effect |
| - | - |
| Any `2xx` | Acknowledged |
| `410` | The subscription is **disabled** until you call [`/enable`](#re-enable-a-subscription) |
| Anything else | Retried on the bounded policy — up to nine attempts over about 76 hours, respecting `Retry-After` up to 24 hours — then dropped |

## Errors

| Status | Meaning |
| - | - |
| `400` | Invalid format; unknown type, argument, filter or operator; impossible range; an argument outside the range its definition declares (`priceMovePct` above `100`, `buckets` above `200`). Nothing is saved. Also `/secret` on an inbox subscription, bad drain parameters and a bad or expired ack receipt |
| `401` | Missing or invalid credentials, in either [authentication mode](#authentication) |
| `403` | The source type is not permitted by your account tier (checked at creation); an inbox subscription on Free |
| `413` | Drain: the oldest pending message does not fit `maxBytes`; the body carries `requiredMaxBytes` |
| `429` | The account's subscription allowance is reached — on create and on `/enable`. Disabled subscriptions do not count toward it |
| `503` | Auth, storage or feed unavailable. An unknown or missing auth tier fails closed. On create, the subscription was rolled back |

Error bodies are **plain text**, not JSON — `Unauthorized`, `unknown webhook type`, `endpoint must be a public HTTPS URL`, `invalid subscription JSON`, `filter "sz" has an impossible range` — so match on the status code and show the text. The tentative subscription allowances per plan are on [Plan limits](https://docs.coinversa.ai/webhooks/limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.