Webhook payload schema (v1)

`X-Botely-Signature: sha256=<hex>` — HMAC-SHA256 of the RAW request body using your webhook secret. Always lowercase hex.

`X-Botely-Timestamp: <unix-ms>` — when Botely signed the request. Reject anything older than ~5 minutes to defend against replay.

`X-Botely-Event-Id: <delivery-id>` — unique per delivery attempt. Use as idempotency key; the same logical event will share the same `signalId` across retries but a new event-id.

Top-level fields: `version` (always `"1"` for now), `eventId`, `signalId`, `clientEventId`, `strategyVersion` (`v6.4`/`v7`), `configHash`, `market`, `action` (`OPEN`/`CLOSE`/`TEST`), `side` (`LONG`/`SHORT`/null), `generatedAt` (ISO).

For OPEN events: nested `open` object with `suggestedPriceLow`, `suggestedPriceHigh`, `suggestedAllocPct`, `tpPct`, `slPct`, `maxHoldHours`, `reasonCode` (e.g. `NR`, `3bc+red+atr_bd+dc`).

For CLOSE events: nested `close` object with `opensSignalId` (the OPEN's signalId), `closeReason` (`TP`/`SL`/`MH`/`FLAT`/`RE`/`EL`/`CLOSE_OPP`/`admin_close`/`cmd_close`/`flip`), `pnlPct`.

```js import crypto from 'node:crypto'; import express from 'express'; const app = express(); const SECRET = process.env.BOTELY_WEBHOOK_SECRET; app.post('/botely-webhook', express.raw({ type: '*/*' }), (req, res) => { const sig = req.header('X-Botely-Signature') || ''; const provided = sig.replace(/^sha256=/, ''); const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex'); if (provided.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(expected, 'hex'))) { return res.status(401).end(); } const ts = Number(req.header('X-Botely-Timestamp')); if (Math.abs(Date.now() - ts) > 5 * 60_000) return res.status(401).end(); const event = JSON.parse(req.body.toString('utf8')); // your code here res.json({ ok: true }); }); ```

```py import hashlib, hmac, time, json from flask import Flask, request, abort app = Flask(__name__) SECRET = os.environ['BOTELY_WEBHOOK_SECRET'].encode() @app.post('/botely-webhook') def receive(): sig = request.headers.get('X-Botely-Signature', '').removeprefix('sha256=') expected = hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest() if not hmac.compare_digest(sig, expected): abort(401) ts = int(request.headers.get('X-Botely-Timestamp', '0')) if abs(time.time()*1000 - ts) > 5*60*1000: abort(401) event = json.loads(request.get_data()) # your code here return {'ok': True} ```

```php <?php $secret = getenv('BOTELY_WEBHOOK_SECRET'); $raw = file_get_contents('php://input'); $sig = $_SERVER['HTTP_X_BOTELY_SIGNATURE'] ?? ''; $provided = preg_replace('/^sha256=/', '', $sig); $expected = hash_hmac('sha256', $raw, $secret); if (!hash_equals($provided, $expected)) { http_response_code(401); exit; } $event = json_decode($raw, true); // your code here header('Content-Type: application/json'); echo json_encode(['ok' => true]); ```