Skip to content

Orders API & Webhooks

Receiving orders (webhook)

Set Delivery mode = My API in the dashboard, with your endpoint URL and a shared secret. RagSystem POSTs each new order:

POST <your-url>
Content-Type: application/json
X-Signature: <hex HMAC-SHA256 of the raw body, keyed with your secret>

{
  "event": "order.created",
  "order": {
    "id": "5dfcd1ae-6121-43ca-aa73-5b287a526ff5",
    "status": "new",
    "customer_name": "Тест Юзер",
    "customer_phone": "+998901112233",
    "note": "",
    "total": "240000",
    "currency": "UZS",
    "channel_type": "telegram",
    "visitor_id": "tg_774411",
    "conversation_id": "…",
    "items": [
      { "product_id": "…", "product_name": "eSIM 10GB", "unit_price": "120000", "quantity": 2 }
    ],
    "created_at": "2026-07-17T09:12:00Z"
  }
}

Escalations arrive on the same endpoint as {"event": "escalation.created", "escalation": {...}}.

Respond with any 2xx quickly; non-2xx responses are retried with backoff, and persistent failures are flagged in the dashboard.

Verifying the signature

Always verify before trusting the payload:

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Reading orders

GET /api/v1/orders?status=new&visitor_id=&page=1&limit=20
GET /api/v1/orders/{id}

Filters: status (new | confirmed | cancelled), visitor_id (a customer's order history).

Deciding an order

PATCH /api/v1/orders/{id}

{ "status": "confirmed", "comment": "courier tomorrow 10:00" }
  • status: confirmed or cancelled (required)
  • The customer is automatically notified in their original chat
  • 404 — no such order in your workspace
  • 409 — already decided (by a Telegram button, the dashboard, or an earlier call); decisions are first-writer-wins