> For the complete documentation index, see [llms.txt](https://offchart.gitbook.io/offchart/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://offchart.gitbook.io/offchart/webhooks.md).

# Webhooks

Webhooks let offchart send events to your server the moment they happen: your bot, trading terminal or Telegram bot gets a signed `POST` request. You don't need to poll the API or keep the live stream open.

{% hint style="info" %}
**Public and private events.** `round.settled` and `fill` are public: everyone's activity, without wallet addresses. The `order.*` events are only about orders of **your** account, and they go only to your endpoints.
{% endhint %}

## Add an endpoint

In the app, open **Wallet menu → API** and find the **Webhooks** panel.

1. Paste your endpoint URL. It must be `https://` and must point at a public address. Local and private addresses (`localhost`, `127.0.0.1`, `10.x`, `192.168.x`, `169.254.169.254` and the like) are refused, also after the DNS lookup.
2. Pick the events.
3. Press **Add endpoint** and copy the **signing secret** (`whsec_…`). It is shown once. **Rotate** gives you a new one, and the old one stops working at once.
4. Press **Send test**. A `ping` event arrives within a few seconds and shows up in the delivery log.

You can have up to 3 endpoints. Each one can be paused, switched back on or deleted. The panel shows the last 20 deliveries for each endpoint: time, event, HTTP code, latency and attempt number.

## Events

| Event                    | When                                                                      |
| ------------------------ | ------------------------------------------------------------------------- |
| `round.settled`          | A matcher round finished (about once a minute), with the swaps it settled |
| `fill`                   | Any swap settled (public, no wallet addresses)                            |
| `order.filled`           | Your order is fully filled                                                |
| `order.partially_filled` | Part of your order was filled                                             |
| `order.cancelled`        | Your order was cancelled                                                  |
| `order.expired`          | Your order expired                                                        |
| `ping`                   | You pressed **Send test**                                                 |

Every request is a `POST` with a JSON body:

```json
{
  "id": "evt_3f6c0d6a8b6e4a5c9a1f2b7d4e8c1a90",
  "type": "order.partially_filled",
  "created_at": "2026-11-12T10:04:31.512Z",
  "data": {
    "order": { "id": "0b9…", "kind": "sell", "status": "partial", "giveMint": "Es9v…", "giveTotal": "100000000", "giveFilled": "40000000", "limitBps": 200, "expiresAt": "…" },
    "fill": { "id": "812", "swapId": "5c1…", "giveAmount": "40000000", "getAmount": "3990000", "getMint": "SOL", "priceVsMarketBps": 210, "signature": "4kZ…", "settledAt": "…" }
  }
}
```

`round.settled` and `fill` carry the same `data` as the live stream (`GET /api/v1/stream`), see [API](https://docs.useoffchart.xyz/api). Amounts are strings in base units.

Headers:

| Header                | Value                                                                          |
| --------------------- | ------------------------------------------------------------------------------ |
| `OffChart-Signature`  | `t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + body)>`                |
| `OffChart-Event-Id`   | The event `id`. It stays the same on every retry, so use it to skip duplicates |
| `OffChart-Event-Type` | The event `type`                                                               |
| `OffChart-Attempt`    | `1` to `5`                                                                     |

## Check the signature

Always check the signature on the **raw** request body, before you parse it, and refuse old timestamps (we suggest 5 minutes).

**Node.js (Express)**

```js
import express from "express"
import { createHmac, timingSafeEqual } from "node:crypto"
const app = express()
app.post("/offchart", express.raw({ type: "application/json" }), (req, res) => {
  const [t = "", v1 = ""] = (req.get("OffChart-Signature") ?? "").split(",").map((p) => p.split("=")[1])
  const want = Buffer.from(createHmac("sha256", process.env.OFFCHART_WHSEC).update(t + "." + req.body).digest("hex"))
  const ok = Buffer.byteLength(v1) === want.length && timingSafeEqual(Buffer.from(v1), want)
  if (!ok || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400)
  const event = JSON.parse(req.body) // { id, type, created_at, data }
  res.sendStatus(200)
})
app.listen(3000)
```

**Python (Flask)**

```python
import hmac, hashlib, json, os, time
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/offchart")
def offchart():
    parts = dict(p.split("=", 1) for p in request.headers.get("OffChart-Signature", "").split(",") if "=" in p)
    t, v1 = parts.get("t", "0"), parts.get("v1", "")
    want = hmac.new(os.environ["OFFCHART_WHSEC"].encode(), f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
    if not t.isdigit() or abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, want): abort(400)
    event = json.loads(request.get_data())  # { id, type, created_at, data }
    return "", 200
```

## Retries

Answer with any `2xx` code within **5 seconds**. Anything else (another code, a timeout, a refused connection) counts as a failure, and we try again:

| Attempt | When             |
| ------- | ---------------- |
| 1       | right away       |
| 2       | 10 seconds later |
| 3       | 1 minute later   |
| 4       | 10 minutes later |
| 5       | 1 hour later     |

After 5 failed attempts the event is dropped. Redirects are not followed. Events can arrive out of order and, rarely, more than once: use `OffChart-Event-Id` to skip duplicates.

After **20 failed deliveries in a row** the endpoint switches itself off. The panel shows it as *off · 20 failures in a row*. Fix your server and switch the endpoint back on. Events from the time it was off are not replayed. A failed `ping` does not count.

## Manage webhooks with the API

With an [API key](https://docs.useoffchart.xyz/api#limits-and-api-keys) you can do the same from code. The key's account owns the endpoints.

```bash
# list (with the last 20 deliveries of each)
curl -s https://useoffchart.xyz/api/v1/webhooks -H "x-api-key: $OFFCHART_KEY"

# add: the answer has the signing secret, once
curl -s -X POST https://useoffchart.xyz/api/v1/webhooks -H "x-api-key: $OFFCHART_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://bot.example.com/offchart","events":["round.settled","order.filled"]}'

# send a test ping / rotate the secret / pause / delete
curl -s -X POST https://useoffchart.xyz/api/v1/webhooks/$ID/test -H "x-api-key: $OFFCHART_KEY"
curl -s -X POST https://useoffchart.xyz/api/v1/webhooks/$ID/rotate -H "x-api-key: $OFFCHART_KEY"
curl -s -X POST https://useoffchart.xyz/api/v1/webhooks/$ID -H "x-api-key: $OFFCHART_KEY" -H "content-type: application/json" -d '{"enabled":false}'
curl -s -X DELETE https://useoffchart.xyz/api/v1/webhooks/$ID -H "x-api-key: $OFFCHART_KEY"
```

Errors: `401 key_required` (no key), `400 https_only`, `400 private_address`, `400 bad_url`, `400 bad_events`, `409 too_many_endpoints` (3 already), `404 not_found`, `429 rate_limited` (more than 5 test pings a minute).
