Skip to main content
Four steps: read the definitions, create a subscription, receive and verify one delivery, delete it. You need an API key from developers.coinversa.ai on a Starter plan or above — Free can read the definitions but has no subscription allowance — and a public HTTPS URL on port 443 that can receive a POST. Every request below goes to 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

The response lists the types your plan may create, each with its 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:
Build your request from this, not from a list you keep yourself: the same declarations drive validation, so a filter the definitions do not list is a 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:
The response carries the subscription — its 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:
Store the secret in your receiver’s secret store, not in source control. It is not in list responses; if you lose it, read it again with GET /v1/subscriptions/{id}/secret.
A few things to know about the body:
  • Numeric filter values are decimal strings ("1", "95000.5"), compared with exact decimal arithmetic. The operators are gt, gte, lt and lte; an exact value is a plain string. All fields combine with AND.
  • Text matching is case-sensitive: BTC is not btc.
  • Impossible ranges ("gt": "10", "lt": "5"), unknown fields and unknown operators are refused with 400 before 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 no url instead, and pull the matches from your account’s inbox.
  • To watch many wallets with one subscription, make args.user an 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 a 400, 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 raw tradesByUser frame — channel, seq and data as the WebSocket feed sends them — plus subscriptionId, with data cut down to the fills that passed your filters:
It is signed the Standard Webhooks way: 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)
Any 2xx acknowledges the delivery; anything else is retried. Return 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

Deleting removes the subscription and, for 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

  1. 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.
  2. Raw body. The route reads the body as bytes before any JSON parser — express.raw, request.body(), request.get_data(), io.ReadAll.
  3. Clock in sync. The libraries reject a webhook-timestamp more than five minutes from your clock. Run NTP.
  4. Deduplicate on webhook-id. Delivery is at least once and retries reuse the id.
  5. Answer, then process. Return 2xx as soon as the frame is verified and queued; do the work afterwards.
  6. Return 410 only on purpose. It disables the subscription; POST /v1/subscriptions/{id}/enable brings it back.
  7. 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.
When something goes wrong, Troubleshooting is ordered by symptom.

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.