https://webhook.coinversa.ai with your key as a Bearer token.
This is the same API key as REST and the WebSocket. Here it travels in the
Authorization: Bearer header, as on the WebSocket upgrade — not in X-API-Key, which is the REST data API’s header.1. Read the definitions
args, its filters — field, type, unit, whether it matches exactly, its options or its numeric operators — and its minTier. The tradesByUser entry looks like this — the other trade filters (side, px, closedPnl) are omitted here for brevity:
400. minItems and maxItems on user say that it takes one address or an array of 1 to 1,000 — one subscription for many wallets.
2. Create a subscription
This one delivers every BTC fill of one wallet with a size of at least 1 BTC:id, type, the normalised args (wallets are lowercased), the saved filters, the url and its disabled status — and, only on creation, the whsec_… signing secret:
- Numeric filter values are decimal strings (
"1","95000.5"), compared with exact decimal arithmetic. The operators aregt,gte,ltandlte; an exact value is a plain string. All fields combine with AND. - Text matching is case-sensitive:
BTCis notbtc. - Impossible ranges (
"gt": "10", "lt": "5"), unknown fields and unknown operators are refused with400before anything is saved. - The URL must be public HTTPS on port 443. Redirects and private or reserved addresses are refused. No server to point at? Send
"deliveryMode": "inbox"and nourlinstead, and pull the matches from your account’s inbox. - To watch many wallets with one subscription, make
args.useran array of 1 to 1,000 addresses. They are lowercased, sorted and deduplicated; a one-element array comes back as a string. An empty array, an invalid address or more than 1,000 entries is a400, and the body may not exceed 64 KiB. One array is one subscription against your allowance (one wallet or many). - The subscription is immutable. To change it, delete it and create it again.
- If your plan does not include the type you get
403; if you are at your plan’s subscription cap,429(Plan limits).
3. Receive and verify a delivery
The next matching frame is POSTed to your URL. The body is the rawtradesByUser frame — channel, seq and data as the WebSocket feed sends them — plus subscriptionId, with data cut down to the fills that passed your filters:
webhook-id, webhook-timestamp and webhook-signature: v1,<base64>, an HMAC-SHA256 over webhook-id + "." + webhook-timestamp + "." + rawBody keyed with your secret. A standardwebhooks library checks all of it. Verify against the raw request body — parsing and re-serialising the JSON changes the bytes.
Node (Express)
410 only if you mean it — it disables the subscription until you re-enable it. Python and Go libraries and a known-answer test vector are on Signatures and delivery.
4. Delete the subscription
priceCross, the cohort bias types and the liquidation risk types, the stored baseline or state and any pending deliveries in the outbox. GET /v1/subscriptions lists what you still have (without secrets); DELETE /v1/subscriptions removes them all.
Before production
- Signature verified against the test vector. Your verifier returns true for the known-answer vector with a fixed clock, and false when you change one byte of the body.
- Raw body. The route reads the body as bytes before any JSON parser —
express.raw,request.body(),request.get_data(),io.ReadAll. - Clock in sync. The libraries reject a
webhook-timestampmore than five minutes from your clock. Run NTP. - Deduplicate on
webhook-id. Delivery is at least once and retries reuse the id. - Answer, then process. Return
2xxas soon as the frame is verified and queued; do the work afterwards. - Return
410only on purpose. It disables the subscription;POST /v1/subscriptions/{id}/enablebrings it back. - Expect gaps after a restart. Retries are in memory and are lost when the service restarts; nothing is replayed. If you need every fill, read the wallet’s history from the REST API when you detect a gap.
What’s next
Subscription types
Every type, its arguments, filters and plan, and a delivery example for each of the six event types.
Signatures and delivery
Standard Webhooks libraries and verifiers; retries, 410, transport rules.
API reference
Every route, body and error code.
Plan limits
Subscriptions per plan, retries, queue slots.

