​

How it works

​

Setup

export CHATCLI_WEBHOOK_ADDR=":8083"
export CHATCLI_WEBHOOK_SECRET="a-long-random-string"
export CHATCLI_WEBHOOK_CALLBACK_URL="https://your-app.example.com/chatcli/replies"
# export CHATCLI_WEBHOOK_PATH="/inbound"   # the default

/gateway start
/gateway status     # webhook should be listed

secret="a-long-random-string"
body='{"chat_id": "ticket-42", "user_id": "alice", "text": "summarize the last deploy log"}'
ts=$(date +%s)
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$secret" -r | cut -d' ' -f1)

curl -X POST http://localhost:8083/inbound \
  -H "Content-Type: application/json" \
  -H "X-ChatCLI-Timestamp: $ts" \
  -H "X-ChatCLI-Signature: sha256=$sig" \
  -d "$body"

​

Environment variables

​

The request

​

Responses

​

The callbacks

{
  "chat_id": "ticket-42",
  "kind": "final",
  "text": "The last deploy finished in 4m12s; two warnings, no errors."
}

​

Delivery and retries

​

Minimal receiver

import hashlib, hmac, json, os, time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

SECRET = os.environ["CHATCLI_WEBHOOK_SECRET"].encode()
seen = set()  # use an expiring store in production

class Callback(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers["Content-Length"]))
        ts = self.headers.get("X-ChatCLI-Timestamp", "")
        want = "sha256=" + hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
        got = self.headers.get("X-ChatCLI-Signature", "")
        if abs(time.time() - int(ts or 0)) > 300 or not hmac.compare_digest(got, want):
            self.send_response(401); self.end_headers(); return
        body = json.loads(raw)
        delivery = self.headers.get("X-ChatCLI-Delivery-ID")
        if delivery not in seen:
            seen.add(delivery)
            if body.get("kind") == "final":
                print(f"[{body['chat_id']}] reply: {body['text']}")
            else:
                print(f"[{body['chat_id']}] {body.get('kind')}: {body['text']}")
        self.send_response(200); self.end_headers()

ThreadingHTTPServer(("0.0.0.0", 8090), Callback).serve_forever()

import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const secret = process.env.CHATCLI_WEBHOOK_SECRET;
const seen = new Set(); // use an expiring store in production

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    const ts = req.headers["x-chatcli-timestamp"] ?? "";
    const want = "sha256=" + createHmac("sha256", secret).update(`${ts}.`).update(raw).digest("hex");
    const got = req.headers["x-chatcli-signature"] ?? "";
    const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
    if (!fresh || got.length !== want.length || !timingSafeEqual(Buffer.from(got), Buffer.from(want))) {
      res.writeHead(401).end();
      return;
    }
    const body = JSON.parse(raw);
    const delivery = req.headers["x-chatcli-delivery-id"];
    if (!seen.has(delivery)) {
      seen.add(delivery);
      console.log(`[${body.chat_id}] ${body.kind}: ${body.text}`);
    }
    res.writeHead(200).end();
  });
}).listen(8090);

​

Conversations and identity

export CHATCLI_HUB_ISOLATE=true

​

Attachments

• audio_b64, image_b64 and document_b64 are decoded on the spot: invalid base64 is refused with 400. Inline base64 is unaffected by the URL rules below.
• audio_url, image_url and document_url are downloaded after the 202, by the gateway itself, up to the CHATCLI_GATEWAY_MAX_AUDIO_BYTES and CHATCLI_GATEWAY_MAX_IMAGE_BYTES caps (20 MB each by default) and CHATCLI_GATEWAY_MAX_DOCUMENT_BYTES (50 MB). An attachment that cannot be downloaded is reported in the reply.
• A URL attachment must be https, and the gateway refuses any address that resolves to a private, loopback, link-local or cloud-metadata target — so a caller holding the secret cannot use the gateway to probe its own network.
• If a download fails, the message still runs and the agent is told, so the reply says the attachment did not arrive instead of answering as if nothing had been sent.

​

Proactive messages

<tool_call name="@send" args='{"cmd":"send","args":{"to":"webhook:ticket-42","message":"Deploy finished ✅"}}' />

​

Security

• Use a long, random secret: it keys the signature in both directions, and the gateway refuses to start without CHATCLI_WEBHOOK_SECRET.
• Verify the signature in your receiver — recompute sha256=HMAC(secret, "<timestamp>.<raw body>") with a constant-time comparison, and reject a timestamp outside ±5 minutes — before trusting the body. The secret is never sent in a header.
• Serve the endpoint and the callback over HTTPS; CHATCLI_WEBHOOK_CALLBACK_URL must be https unless its host is loopback.
• audio_url and image_url are fetched by the gateway itself, so they are restricted to https and blocked from private, loopback, link-local and metadata addresses.

​

Limits

• A reply is cut at 3500 characters and ends with ….
• The request body fits the largest audio, image and PDF accepted, all base64-encoded, plus 1 MB: about 121 MB with the default caps. Past that, 413.
• Up to 32 messages waiting per conversation; past that, 429.
• Only text and images come back in the callback; voice replies are not sent on this channel.

​

See also