410 to worry about; what you give up is the push.
Every account has one implicit inbox, shared by all its API keys and all its inbox subscriptions. Nothing creates it and nothing names it: the first inbox subscription starts filling it, and GET /v1/inbox reads it. Every request on this page goes to https://webhook.coinversa.ai with the same authentication as the rest of the webhook API.
Create an inbox subscription
Same types, sameargs, same filters as an HTTP subscription — set "deliveryMode": "inbox" and send no url:
deliveryModeishttpby default — omitting it keeps the behaviour the rest of these pages describe, and thenurlis required. Create and list responses carrydeliveryMode("http"or"inbox") on every subscription.- An inbox subscription takes one of the same subscription slots as an HTTP subscription (Plan limits).
- It has no signing secret: the create response carries none, and
GET /v1/subscriptions/{id}/secretanswers400for it. - Free has no inbox: creating an inbox subscription on Free is
403. Starter and above can. - Like every subscription it is immutable — delete and recreate to change it — and it is a creation-time tier check, not continuous re-authorisation.
The message
Each stored message is one delivery envelope as the delivered frame describes it —channel, seq, subscriptionId and the filtered data array — with two fields added at the same level, not in a wrapper:
- Messages come back oldest first by insertion, not by
seqand not by event time.seqvalues from different sources are not comparable (sequence numbers). - Two subscriptions that match the same source record produce two messages, one per
subscriptionId. - Deleting a subscription stops collection but does not delete the messages it already stored. They stay until you acknowledge them, they expire or overflow evicts them.
- The sources are live-only: the inbox stores what the service saw while it was running. It is not a replay of frames missed during a service outage, and a
priceCrosscrossing during an outage is not reconstructed. - The 1 MiB cap on one delivery applies to an inbox message too. Inbox messages bypass the HTTP workers, signing, retries and the outbox cap of
priceCross, the cohort bias types and the liquidation risk types; for those types the state change and the inbox append commit together.
State
GET /v1/inbox → {"state": {...}}. Successful drain and ack responses carry the same snapshot under state:
The two counters are account-wide and persistent, and reading does not reset them: keep your last snapshot and compare to see whether you lost anything since. Expiry and overflow are counted separately.
Drain: read without deleting
POST /v1/inbox/drain takes no body and two optional query parameters:
- Drain removes nothing. It does not lease or lock either: a repeated or concurrent drain returns the same pending messages, and a failed response leaves everything pending. Only an ack deletes.
batchIdis an opaque receipt for this batch, bound to your account, which an ack can refer to. An empty inbox returns an emptybatchId.hasMoremeans more pending messages existed beyond this batch at the time of the read — not that the returned ones have been consumed.- Messages are never split, skipped or truncated to fit
maxBytes. If the oldest pending message does not fit, the response is413with emptymessages, an emptybatchId, thestate, andrequiredMaxBytes: retry with at least that budget. - A malformed, unknown or duplicated query parameter is
400. - Responses are
no-store: nothing on the way caches a drain.
Acknowledge
POST /v1/inbox/ack deletes messages. The body is one of two shapes:
count acknowledges an absolute prefix of that batch — the first count messages the drain returned — never a count against whatever is pending now. After draining ten, count: 5 deletes the first five; sending it again deletes nothing more; a later count: 10 on the same receipt deletes the remaining five, not ten newer messages. count must be between 1 and the number of messages in that batch. A receipt is bound to your account, survives a service restart and expires after 14 days; an invalid, tampered, expired or other-account receipt is 400. Never send a bare count without its batchId.
By message id. inboxIds takes 1 to 1,000 ids. Only this account’s listed messages are deleted; an id that is already acknowledged, expired, evicted, unknown or another account’s has no effect and is not an error.
Both forms are idempotent, and an old receipt cannot delete messages that replaced its batch after overflow or expiry. The response is:
acknowledged counts the rows this request removed, so a retried ack legitimately returns 0 — that is the idempotency working, not a lost ack (troubleshooting).
Limits
- 2 GiB of compressed payload per account, independent of the message count.
pendingBytesandmaxStoredBytesin the state are this cap. - Messages older than 14 days are deleted — on service startup, every minute, and lazily when your inbox is read or written. They count in
expiredTotal. - On overflow of either limit, the oldest pending messages are evicted until both hold again. They count in
overflowDroppedTotal. - Your plan’s limits are refreshed when you make an inbox request or create or re-enable an inbox subscription, and incoming messages are held to the most recently seen plan. A lower limit evicts the oldest messages at that refresh. An account that never makes another request is not re-checked.
- Inbox subscriptions count against the same subscription allowance as HTTP ones (Plan limits).
For agents: drain, process, ack
The inbox is what lets an agent use webhooks with no receiver. The loop is three steps, and the order matters:- Drain with a
countandmaxBytessized for what you can show or process in one go. - Process the messages — read
dataas the WebSocket fill objects, liquidation objects, TWAP status records, crossing events, cohort rows or liquidation risk positions and exposure they are. - Ack exactly what you processed: the
inboxIdsyou exposed, or the prefixcountyou exposed, against that drain’sbatchId— not the whole fetched batch if you dropped some of it on the way.
inbox_subscribe creates inbox subscriptions and inbox_drain runs steps 1 and 3 in one call — it acknowledges the messages it returns, so a drain from chat consumes them. See Webhooks for agents.
Errors on the inbox routes
Errors are plain text in the body, as on the rest of the webhook API.

