> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks quickstart

> Set up a Coinversa Pulse webhook in four steps — read the subscription definitions, create a tradesByUser subscription with a coin and size filter over curl with Bearer auth, receive and verify one Standard Webhooks-signed delivery, and delete the subscription.

Four steps: read the definitions, create a subscription, receive and verify one delivery, delete it. You need an API key from [developers.coinversa.ai](https://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.

> [!NOTE]
>
> 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

```bash theme={null}
curl https://webhook.coinversa.ai/v1/subscriptions/definitions \
  -H "Authorization: Bearer $COINVERSA_API_KEY"
```

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:

```json theme={null}
{
  "type": "tradesByUser",
  "args": {"user": {"type": "address", "required": true, "minItems": 1, "maxItems": 1000}},
  "filters": {
    "coin": {"type": "string", "label": "Market", "exact": true},
    "sz": {
      "type": "decimal", "label": "Size", "unit": "base",
      "exact": true, "operators": ["gt", "gte", "lt", "lte"]
    }
  },
  "minTier": "free"
}
```

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:

```bash theme={null}
curl -X POST https://webhook.coinversa.ai/v1/subscriptions \
  -H "Authorization: Bearer $COINVERSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tradesByUser",
    "args": {"user": "0x28f0d2a7c6b3e14f9a8b7c6d5e4f3a2b1c0d9bad"},
    "filters": {"coin": "BTC", "sz": {"gte": "1"}},
    "url": "https://example.com/hooks/coinversa"
  }'
```

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:

```json theme={null}
{
  "id": "…",
  "type": "tradesByUser",
  "args": {"user": "0x28f0d2a7c6b3e14f9a8b7c6d5e4f3a2b1c0d9bad"},
  "filters": {"coin": "BTC", "sz": {"gte": "1"}},
  "url": "https://example.com/hooks/coinversa",
  "disabled": false,
  "secret": "whsec_…"
}
```

> [!WARNING]
>
> 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](https://docs.coinversa.ai/webhooks/inbox.md).
* 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](https://docs.coinversa.ai/webhooks/events.md#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](https://docs.coinversa.ai/webhooks/limits.md)).

## 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](https://docs.coinversa.ai/websocket/feeds.md#the-fill-object) sends them — plus `subscriptionId`, with `data` cut down to the fills that passed your filters:

```json theme={null}
{
  "channel": "tradesByUser",
  "seq": 928110001,
  "subscriptionId": "…",
  "data": [
    [
      "0x28f0d2a7c6b3e14f9a8b7c6d5e4f3a2b1c0d9bad",
      {
        "coin": "BTC",
        "px": "70000.5",
        "sz": "1.25",
        "side": "B",
        "time": 1788324615827,
        "startPosition": "0.0",
        "dir": "Open Long",
        "closedPnl": "0.0",
        "hash": "0xcdade62a4403e265cf2704437fc43c0201ec000fdf0701377176917d0307bc50",
        "oid": 533649007948,
        "crossed": true,
        "fee": "0.0245",
        "tid": 905724619509577,
        "feeToken": "USDC",
        "twapId": null
      }
    ]
  ]
}
```

It is signed the [Standard Webhooks](https://www.standardwebhooks.com) 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.

```javascript Node (Express) theme={null}
import express from "express";
import { Webhook } from "standardwebhooks"; // npm install standardwebhooks

const app = express();
const wh = new Webhook(process.env.COINVERSA_WEBHOOK_SECRET); // the whsec_… from step 2

app.post("/hooks/coinversa", express.raw({ type: "application/json" }), (req, res) => {
  let frame;
  try {
    frame = wh.verify(req.body.toString("utf8"), req.headers); // throws on a bad signature or stale timestamp
  } catch (err) {
    return res.status(400).send("bad signature");
  }
  // Deduplicate on req.headers["webhook-id"], then hand frame.data off to a queue.
  res.sendStatus(200);
});
```

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](https://docs.coinversa.ai/webhooks/signatures.md).

## 4. Delete the subscription

```bash theme={null}
curl -X DELETE https://webhook.coinversa.ai/v1/subscriptions/$SUB_ID \
  -H "Authorization: Bearer $COINVERSA_API_KEY"
```

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](https://docs.coinversa.ai/webhooks/signatures.md#known-answer-test-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](https://docs.coinversa.ai/quickstart.md) when you detect a gap.

When something goes wrong, [Troubleshooting](https://docs.coinversa.ai/webhooks/troubleshooting.md) is ordered by symptom.

## What's next

> [card] [Subscription types](https://docs.coinversa.ai/webhooks/events.md)
>
> Every type, its arguments, filters and plan, and a delivery example for each of the six event types.

> [card] [Signatures and delivery](https://docs.coinversa.ai/webhooks/signatures.md)
>
> Standard Webhooks libraries and verifiers; retries, 410, transport rules.

> [card] [API reference](https://docs.coinversa.ai/webhooks/api.md)
>
> Every route, body and error code.

> [card] [Plan limits](https://docs.coinversa.ai/webhooks/limits.md)
>
> Subscriptions per plan, retries, queue slots.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.