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 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).
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 and read what the subscriptions matched from the inbox, with no server at all.
The types
Six event types:
* 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.
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).
And four cohort bias types, which report how a trader cohort is positioned on one coin — its net bias, from -1 (all short) to 1 (all long):
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.
And four liquidation risk types, which report potential liquidation exposure — two for one wallet’s positions, two for a whole market.
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.
Every type, its arguments and filters are on Subscription types, with a delivery example for each event type; the cohort bias delivery examples are on Cohort bias types and the liquidation risk ones on Liquidation risk types. 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).
How it relates to the WebSocket feeds
Same data, pushed to a URL. AtradesByUser 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 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).
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). 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 onePOST to the subscription’s url, signed the Standard Webhooks 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).
- Any 2xx acknowledges. Anything else is retried on a bounded back-off, respecting your
Retry-Afterup 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.
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 use by default. See Inbox delivery.
Subscriptions are immutable
A subscription’stype, 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.
Where to manage it
- The developer portal at developers.coinversa.ai.
- The REST API at
https://webhook.coinversa.aiwithAuthorization: Bearer <your API key>— see the API reference. - The MCP server — tools to create, list and delete inbox subscriptions and to read the inbox from chat; see Webhooks for agents.
Quickstart
Read the definitions, create a subscription, verify one delivery, delete it.
Subscription types
Every type with its arguments, filters and plan, and delivery examples for the six event types.

