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

> Coinversa Pulse webhooks — subscribe to a Hyperliquid wallet's fills, TWAP fills or TWAP statuses, to exchange-wide or per-wallet liquidations, to a price crossing a level, or to a trader cohort's net long or short bias on a coin, and receive the frames as Standard Webhooks-signed HTTPS POSTs to your URL, or store them in your account's inbox to pull later. Six event types, four cohort bias types and four liquidation risk types, exact decimal filters, Bearer auth with your API key.

**Webhooks** push the same data the [WebSocket](https://docs.coinversa.ai/websocket/overview.md) streams, to a URL you own, so you do not have to hold a socket open. You create a **subscription** — a **type** (which feed), its `args` (which wallet — or up to 1,000 wallets — or which market), optional `filters` (which frames you want) and the `url` to deliver to — and every matching frame is POSTed to that URL, signed with the subscription's own **signing secret**. A subscription with `"deliveryMode": "inbox"` and no URL stores its matches in your account's **[inbox](https://docs.coinversa.ai/webhooks/inbox.md)** instead, for you or an agent to pull.

What arrives is the **raw source frame** — the same `channel`, `seq` and `data` the WebSocket sends — plus the `subscriptionId` it matched, with `data` cut down to the events that passed your filters. There is no envelope, no summary and no derived fields: a client that already reads the WebSocket feeds reads a webhook body unchanged. `priceCross`, the four cohort bias types and the four liquidation risk types are the exception: they build their own events, in the same frame ([below](#how-it-relates-to-the-websocket-feeds)).

## Who it is for

* **Servers and bots** that would rather be called than poll or hold a connection — a Lambda, a Cloud Run service, a Zapier / Make / n8n catch hook.
* **Alerting**: a wallet's fills above a size, a liquidation on a watched account, a price crossing a level, a trader cohort changing side on a coin.
* **Agents** that subscribe from chat through the [MCP tools](https://docs.coinversa.ai/webhooks/agents.md) and read what the subscriptions matched from the inbox, with no server at all.

## The types

Six event types:

| Type | What it delivers | `args` | Filters | Minimum plan |
| - | - | - | - | - |
| `tradesByUser` | Every fill of one wallet, or of up to 1,000 wallets, TWAP fills included | `user` | `coin`, `side`, `px`, `sz`, `closedPnl` | Free data\* |
| `twapSliceFillsByUser` | The fills a wallet's TWAP orders executed | `user` | `coin`, `side`, `px`, `sz`, `closedPnl` | Free data\* |
| `twapStatusesByUser` | The node's raw TWAP status records for one wallet or up to 1,000 | `user` | `coin`, `status`, `sz`, `executedSz`, `executedNtl`, `minutes` | Pro |
| `liquidations` | Every liquidation on the exchange | none | `coin`, `side`, `px`, `sz`, `closedPnl` | Agent |
| `liquidationsByUser` | Liquidations of one account, or of up to 1,000 (the liquidated side) | `user` | `coin`, `side`, `px`, `sz`, `closedPnl` | Agent |
| `priceCross` | A market's mark or trade price crossing a threshold | `coin`, `threshold`, `source`, `direction` | none — the condition is in `args` | Free data\* |

\* Free-tier data, but Free's subscription allowance is **zero**, so creating one takes Starter or above. Feed access and the subscription allowance are separate checks — see [Plan limits](https://docs.coinversa.ai/webhooks/limits.md).

On the four by-user types `user` is one address or an array of 1 to 1,000 addresses — one subscription, one allowance slot, for many wallets ([one wallet or many](https://docs.coinversa.ai/webhooks/events.md#one-wallet-or-many)).

And four **cohort bias** types, which report how a [trader cohort](https://docs.coinversa.ai/concepts/cohorts.md) is positioned on one coin — its net bias, from `-1` (all short) to `1` (all long):

| Type | What it delivers | `args` | Filters | Minimum plan |
| - | - | - | - | - |
| `cohortBias` | The cohort rows of each new snapshot, and the current state once when the subscription is created | `coin`, `cohort`, `tierType` | `netBias`, `longNotional`, `shortNotional`, `accountCount` | Starter |
| `cohortBiasFlip` | A cohort's net bias going from long to short, or from short to long | `coin`, `cohort`, `direction`, `tierType` | `netBias`, `longNotional`, `shortNotional`, `accountCount` | Starter |
| `cohortBiasOpposition` | Two cohorts entering opposite positioning | `coin`, `cohort`, `otherCohort`, `tierType` | none — the condition is in `args` | Starter |
| `cohortBiasMove` | A cohort's net bias moving at least a number of percentage points | `coin`, `cohort`, `points`, `tierType` | `netBias`, `longNotional`, `shortNotional`, `accountCount` | Starter |

Cohort positioning is a stored snapshot, normally taken every 15 minutes, so these four tell you about a change **at the next snapshot** — not when a trade happens. See [Cohort bias types](https://docs.coinversa.ai/webhooks/cohort-bias.md).

And four **liquidation risk** types, which report potential liquidation exposure — two for one wallet's positions, two for a whole market.

| Type | What it delivers | `args` | Filters | Minimum plan |
| - | - | - | - | - |
| `liquidationRiskCross` | A position of one wallet whose distance to its liquidation price crosses a threshold | `user`, `liquidationDistancePct`, `direction` | none — the condition is in `args` | Starter |
| `liquidationRisk` | A position of one wallet whose distance to its liquidation price has moved at least a number of percentage points | `user`, `points` | `liquidationDistancePct` | Starter |
| `liquidationExposure` | A market where at least a set notional has liquidation levels within a price move from the mark | `coin`, `priceMovePct`, `minNotional`, `direction`, `resetNotional` | none — the condition is in `args` | Starter |
| `liquidationMap` | A market's full liquidation map, after the mark has moved by a percentage | `coin`, `priceChangePct`, `buckets`, `range` | none — the condition is in `args` | Starter |

These are positions that are still open — not executed liquidations, which are `liquidations` and `liquidationsByUser` above. The service checks about once a minute, using positions and liquidation levels as last stored. On the two wallet types `user` is exactly one wallet. See [Liquidation risk types](https://docs.coinversa.ai/webhooks/liquidation-types.md).

Every type, its arguments and filters are on [Subscription types](https://docs.coinversa.ai/webhooks/events.md), with a delivery example for each event type; the cohort bias delivery examples are on [Cohort bias types](https://docs.coinversa.ai/webhooks/cohort-bias.md) and the liquidation risk ones on [Liquidation risk types](https://docs.coinversa.ai/webhooks/liquidation-types.md). The machine-readable version is `GET /v1/subscriptions/definitions`, which lists the types **your** plan may create with their `args`, `filters` and `minTier` — read it instead of hard-coding this table ([reference](https://docs.coinversa.ai/webhooks/api.md#definitions)).

## How it relates to the WebSocket feeds

Same data, pushed to a URL. A `tradesByUser` subscription delivers the frames a `tradesByUser` WebSocket subscription would stream, filtered; `liquidations` and `liquidationsByUser` deliver liquidation objects; `twapStatusesByUser` delivers the node's status records. `priceCross` has no WebSocket twin: it watches a market's mark or trade price and synthesises its own `channel: "priceCross"` frame when the price crosses your threshold. The four cohort bias types do not come from the fill stream at all: they are built from stored cohort positioning snapshots, and their `data` holds [cohort rows](https://docs.coinversa.ai/webhooks/cohort-bias.md#the-cohort-row) in the same `channel`, `seq`, `subscriptionId`, `data` frame. The four liquidation risk types are built the same way, from stored positions and liquidation levels ([delivered fields](https://docs.coinversa.ai/webhooks/liquidation-types.md#delivered-fields)).

Two differences from the socket. A webhook body carries **`subscriptionId`**, which a WebSocket data frame does not, so one receiver can tell its subscriptions apart. And `data` holds **only the events that matched your filters** — a frame with no match is not delivered at all.

Treat `seq` as a per-source position, as on the socket: trade prices use the block height, mark prices use the replica's Unix nanoseconds — never compare the two ([sequence numbers](https://docs.coinversa.ai/websocket/protocol.md#sequence-numbers)). The cohort bias and liquidation risk types use a third kind: the Unix microseconds at which the snapshot or observation was read.

## Delivery model

Each delivery is one `POST` to the subscription's `url`, signed the **[Standard Webhooks](https://www.standardwebhooks.com)** way: `webhook-id`, `webhook-timestamp` and `webhook-signature` headers, `v1` HMAC-SHA256 over `id.timestamp.body`, verified by the off-the-shelf `standardwebhooks` library for your language ([Signatures and delivery](https://docs.coinversa.ai/webhooks/signatures.md)).

* Any **2xx** acknowledges. Anything else is retried on a bounded back-off, respecting your `Retry-After` up to 24 hours, for up to **nine attempts over about 76 hours**.
* Retries are kept **in memory**: a restart of the service drops them. Only `priceCross`, cohort bias and liquidation risk deliveries sit in a durable outbox that survives restarts.
* Delivery is **at least once**, and order across deliveries and retries is not guaranteed. Deduplicate on `webhook-id`.
* A **410** from your URL disables the subscription until you re-enable it with `POST /v1/subscriptions/{id}/enable`.
* The URL must be public **HTTPS on port 443**; redirects and private or reserved addresses are refused when you create the subscription.

Nothing is stored after an HTTP delivery is acknowledged or gives up: there is no delivery history, no replay and no test send. If you need to see what your receiver got, log it on your side.

## Or pull from the inbox

If you have no server to receive a POST, create the subscription with `"deliveryMode": "inbox"` and **no `url`**. The frames it matches are stored in your account's one **inbox** — the same envelope, plus an `inboxId` and the time it was received — and you read them with `POST /v1/inbox/drain`, which deletes nothing, then `POST /v1/inbox/ack` for the ones you have processed. An inbox subscription takes the same slot as an HTTP one and has no signing secret; pending messages are capped per plan (Starter 1,000, Agent 50,000, Pro and Enterprise 1,000,000, Free none), kept for 14 days under a 2 GiB cap, with the oldest evicted on overflow. It is the delivery mode the [MCP tools](https://docs.coinversa.ai/webhooks/agents.md) use by default. See [Inbox delivery](https://docs.coinversa.ai/webhooks/inbox.md).

## Subscriptions are immutable

A subscription's `type`, `args`, `filters`, `deliveryMode` and `url` cannot be edited. To change one, delete it and create it again — which also resets a `priceCross` subscription's crossing baseline and a cohort bias or liquidation risk subscription's state. Each HTTP subscription has one signing secret, returned once at creation and readable later with `GET /v1/subscriptions/{id}/secret`; an inbox subscription has none.

Subscriptions belong to your **account**, not to the API key that created them: any of your keys can list, delete or re-enable them. Your plan caps how many you can have — see [Plan limits](https://docs.coinversa.ai/webhooks/limits.md).

## Where to manage it

* The **developer portal** at [developers.coinversa.ai](https://developers.coinversa.ai).
* The **REST API** at `https://webhook.coinversa.ai` with `Authorization: Bearer <your API key>` — see the [API reference](https://docs.coinversa.ai/webhooks/api.md).
* The **MCP server** — tools to create, list and delete inbox subscriptions and to read the inbox from chat; see [Webhooks for agents](https://docs.coinversa.ai/webhooks/agents.md).

> [card] [Quickstart](https://docs.coinversa.ai/webhooks/quickstart.md)
>
> Read the definitions, create a subscription, verify one delivery, delete it.

> [card] [Subscription types](https://docs.coinversa.ai/webhooks/events.md)
>
> Every type with its arguments, filters and plan, and delivery examples for the six event types.


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