Skip to main content
Start from what you see. There is no delivery log on our side — nothing is stored after an HTTP delivery — so the places to look are GET /v1/subscriptions (reference), GET /v1/inbox for inbox subscriptions (reference), the unauthenticated GET /health (reference) and your own receiver’s logs.

400 when creating a subscription

The body failed validation and nothing was saved. The usual causes:
  1. Impossible range. {"gt": "10", "lt": "5"} can never match. Equal endpoints are allowed only when both are inclusive: {"gte": "10", "lte": "10"} is fine, {"gt": "10", "lte": "10"} is not.
  2. Unknown filter or operator. Only the fields the type declares in GET /v1/subscriptions/definitions and only gt, gte, lt, lte are accepted — no eq, no $gt, no nested paths. priceCross, cohortBiasOpposition, liquidationRiskCross, liquidationExposure and liquidationMap take no filters at all.
  3. A number that is not a decimal string. 1.5 must be "1.5"; exponent notation, NaN, infinity and 1/2 are rejected; the maximum length is 128 characters.
  4. Unknown type or argument. Check the spelling against the definitions; user sent both at the top level and inside args is also a 400.
  5. A missing required argument. user on the four by-user types, coin and threshold on priceCross (a positive decimal string), coin on the four cohort bias types, plus cohort on cohortBiasFlip, cohortBiasOpposition and cohortBiasMove, otherCohort on cohortBiasOpposition and points on cohortBiasMove. On the liquidation risk types: user and liquidationDistancePct on liquidationRiskCross, user and points on liquidationRisk, coin, priceMovePct and minNotional on liquidationExposure, coin and priceChangePct on liquidationMap.
  6. A cohort bias argument out of range. A cohort that does not belong to the chosen tierType (heavyweights with pnl), the same cohort twice on cohortBiasOpposition, or points that is not a decimal string above 0 and at most 200 (arguments).
  7. A liquidation risk argument out of range. priceMovePct that is not above 0 or is above 100; resetNotional above minNotional; buckets that is not an integer string from "1" to "200", or range that is not one from "1" to "100" — "1.5" and "0" are refused; a threshold that is not a positive decimal string (arguments).
  8. A bad wallet array. args.user may be one address or an array of 1 to 1,000; an empty array, an invalid address or more than 1,000 entries is refused, as is a creation body over 64 KiB. On liquidationRiskCross and liquidationRisk it is exactly one wallet: a second address is refused.

403 when creating a subscription

The type is above your plan: liquidations and liquidationsByUser need Agent, twapStatusesByUser needs Pro. The definitions endpoint only lists what your plan may create, so a type you did not see there will be refused. See Types per plan. The other cause is an inbox subscription on Free: "deliveryMode": "inbox" needs Starter or above, because Free’s inbox holds zero messages (the inbox).

429 when creating or enabling

Your account is at its subscription allowance — tentatively 2 on Starter, 6 on Agent, 10 on Pro, 20 on Enterprise, and 0 on Free. Delete a subscription you no longer need (GET /v1/subscriptions to find it), or move up a plan. A disabled subscription does not count toward the allowance, which is why POST /v1/subscriptions/{id}/enable can be refused with 429 too. See Plan limits.

Deliveries stopped and the subscription shows disabled: true

Your URL answered 410 Gone to a delivery. That disables the subscription at once; frames matched while it is disabled are not kept. Fix whatever returned the 410, then:
The call is idempotent. If it answers 429, you are at your allowance with the disabled one re-counted — delete another subscription first. A framework that answers 410 for an unknown route, or a proxy that does during a deploy, is the usual cause; make the route answer 404 or 503 instead for anything but a deliberate stop.

Nothing arrived, and the service restarted

Ordinary deliveries and their retries are kept in memory. When the webhook service restarts — a deploy, a crash — whatever was queued or waiting to retry is lost, and nothing is replayed afterwards. Your subscription is still saved and starts delivering again on the next matching frame. If your receiver was down at the same time, the frames it missed are gone from the webhook side: read the wallet’s fills from the REST API or the WebSocket to fill the gap. priceCross behaves differently: its deliveries sit in a durable outbox and survive a restart, though a crossing that happened entirely during an outage of the source cannot be reconstructed. The four cohort bias types use the same outbox; after an outage they compare the newest snapshot with the last one they saw, and the snapshots in between are not replayed. The four liquidation risk types use it too; what happened between two checks, or during an outage, is not replayed either.

Nothing arrives, and the service did not restart

  1. Is the subscription there and enabled? GET /v1/subscriptions. A disabled: true means a 410 — see above.
  2. Do the filters match? Exact text is case-sensitive (BTC, not btc); side is A for sell and B for buy; sizes are in the market’s base unit and prices in its quote, so a sz bound of "100000" on BTC never matches. A missing or null field never satisfies a numeric filter, so a closedPnl bound only matches fills that carry one.
  3. Is it the right wallet? liquidationsByUser selects the liquidated account, not the liquidator’s fills; twapSliceFillsByUser only carries fills with a twapId.
  4. Is it a cohort bias type? These read a stored snapshot, normally taken every 15 minutes. The first delivery of a cohortBias subscription follows its creation at the service’s next check, about once a minute; after it, nothing arrives before the next snapshot. cohortBiasFlip, cohortBiasOpposition and cohortBiasMove deliver only on a change between two snapshots: the snapshot already stored when you subscribe only sets the starting state, so the next new snapshot is the first that can fire; a cohort that stays on one side never fires a flip. coin is not checked against a list of markets, so a symbol with no snapshot rows is accepted and delivers nothing (snapshot timing).
  5. Is it a liquidation risk type? Those have their own list, below.
  6. Is your receiver acknowledging? Only a 2xx counts. A 200 after a long handler may already have timed out on our side and been retried; answer first, process after.
  7. Is the receiver’s queue share full? A subscription holds at most 16 slots across the fresh and retry pools; a failing receiver saturates its own share and its newest frames are dropped. Fix the receiver and the subscription resumes on its own.
  8. Is the service healthy? GET /health answers 200 while the service is up, with service counts in the body (reference).

A liquidation risk subscription delivers nothing

You subscribed to liquidationRiskCross, liquidationRisk, liquidationExposure or liquidationMap and received nothing. Go through the checks above first, then these:
  1. Has a check run yet? The service checks about once a minute, using positions and liquidation levels as last stored. It does not follow every price tick, and a move that happens and reverses between two checks is not seen.
  2. Is the condition met? Nothing is sent while it is not:
    • liquidationRiskCross needs the distance to cross the threshold. Reaching it exactly is not a crossing, and a position that stays on one side fires at most once — on its first observation, if it is already on the side you asked for.
    • liquidationRisk fires on the first observation of a position that passes your liquidationDistancePct filter — without a filter, its first valid observation. After that it needs a move of at least points percentage points from the last notified reading, with the filter still passing.
    • liquidationExposure needs at least minNotional within the move. After it fires, exposure must fall strictly below resetNotional before it can fire again.
    • liquidationMap needs the mark to move at least priceChangePct from the reference price.
  3. Is it the first observation of a liquidationMap subscription? That one only records the reference price — no map is sent. The first map follows a later check where the mark is at least priceChangePct away from it.
  4. Is there a recent mark price tick? liquidationExposure and liquidationMap need a tick for the market that is less than five minutes old. Without one they send nothing — not a zero — and the check is skipped until one arrives.
  5. Is the wallet or the market on record? coin is not checked against a list of markets, and a wallet is not checked for positions, when you create the subscription. A symbol with no recent mark price, or a wallet with no open positions on record, is accepted and delivers nothing. A position without a usable mark or liquidation price is skipped.
  6. Still nothing? If the conditions above hold and nothing arrives, email chat@coinversa.ai with the subscription id and what you expected.
What each type fires on, and its timing, are on Liquidation risk types.

The URL was refused

The url must be public HTTPS on port 443, reached without a redirect. Refused at creation:

400 reading a subscription’s secret

GET /v1/subscriptions/{id}/secret answers 400 for an inbox subscription, because it has no signing secret: nothing is POSTed, so nothing is signed. Check deliveryMode in GET /v1/subscriptions — "inbox" subscriptions are read with POST /v1/inbox/drain, not verified. If you need both a URL and the inbox for the same wallet, create two subscriptions; each takes a slot.

413 on an inbox drain

The oldest pending message does not fit the maxBytes budget you gave POST /v1/inbox/drain — the budget covers the whole JSON response, receipt and state included, and messages are never split or skipped to fit. The 413 body carries the state and requiredMaxBytes; retry with at least that value (the parameter accepts up to 4,194,304). A message is at most 1 MiB, so a budget at the maximum always fits. Nothing was deleted or skipped by the failed call. See Drain.

acknowledged: 0 on an ack

Usually nothing is wrong. acknowledged counts the rows this request removed, and acknowledgements are idempotent, so a retried {"batchId", "count"} or {"inboxIds"} that already succeeded returns 0 — the messages are gone, which is what you wanted. Three other ways to get 0:
  1. The prefix was already acknowledged. count is an absolute prefix of that batch: after count: 5, another count: 5 on the same receipt is a no-op, and count: 10 deletes only the next five.
  2. The messages expired or were evicted before your ack: they are counted in expiredTotal or overflowDroppedTotal in the returned state, not in acknowledged. An old receipt cannot delete the messages that replaced them.
  3. The ids are not this account’s, or are unknown. Explicit inboxIds only ever delete your own messages; others are ignored, not errors.
A 400 is different: the receipt is invalid, tampered, expired (14 days) or belongs to another account, or count is outside 1 to the batch size. Drain again for a fresh batchId. See Acknowledge.

The inbox is filling up, or messages disappeared

Compare two GET /v1/inbox snapshots. A rising expiredTotal means messages sat unacknowledged for 14 days; a rising overflowDroppedTotal means you hit your plan’s pending-message limit or the 2 GiB cap and the oldest were evicted. Both counters are cumulative and never reset. Drain and ack more often, ack what you have processed rather than leaving it, or move up a plan (the inbox). Deleting a subscription does not clear its stored messages — acknowledge them if you no longer want them.

Signature mismatch

Check your verifier against the known-answer test vector first — it isolates your code from your framework. Then, in order of how often each is the cause:
  1. The body was re-serialised. You verified JSON.stringify(req.body), not the bytes received. Use express.raw, await request.body(), request.get_data() or io.ReadAll(r.Body) on the webhook route.
  2. Wrong signed content. It is webhook-id + "." + webhook-timestamp + "." + body — the id first.
  3. Wrong secret. Each subscription has its own; if one receiver serves several, look the secret up by the body’s subscriptionId. GET /v1/subscriptions/{id}/secret returns the current one.
  4. A hand-rolled HMAC. Verify with a standardwebhooks library for your language; it takes the whsec_… secret as you received it and handles the key.
  5. Hex instead of base64. The signature is standard base64, after the v1, prefix.
  6. Clock skew. The libraries reject a webhook-timestamp more than five minutes from your clock. Run NTP.

Duplicate deliveries

Expected: delivery is at least once, and order is not guaranteed across workers and retries. A retry follows any failure we observed, including a timeout after your handler already succeeded. Deduplicate on webhook-id, which is stable across the retries of one delivery, and order by seq within one source if order matters. If two different ids carry the same fill, check whether two of your subscriptions match it — each delivers on its own.

Still stuck

Email chat@coinversa.ai with the subscription id, the webhook-id of a delivery if you have one, and what you expected. Never send your signing secret.