Connect a web agent

{"v":1,"conversationId":"run_7f3a9c2e1b","message":"Hi, I need to change the email on my account right now."}

POST /api/agent HTTP/1.1
Host: chat.example.com
content-type: application/json
accept: application/json
x-db-signature: t=1762790400,v1=3f1c0d7b9a2e4c6d8b0f1a2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60

# Send one signed test message to your own endpoint.
KEY='<your signing key>'
URL='https://chat.example.com/api/agent'
PATH_AND_QUERY='/api/agent'
BODY='{"v":1,"conversationId":"test-1","message":"Hello, is anyone there?"}'
T=$(date +%s)
SIG=$(printf '%s.POST %s\n%s' "$T" "$PATH_AND_QUERY" "$BODY" \
  | openssl dgst -sha256 -hmac "$KEY" | sed 's/^.* //')

curl -sS -X POST "$URL" \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H "x-db-signature: t=$T,v1=$SIG" \
  --data-binary "$BODY"

// Express. Keep the raw body: the signature covers the exact bytes.
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const KEY = process.env.DEEPBLOCKER_SIGNING_KEY!;
const WINDOW_SEC = 300;

function verify(header: string | undefined, pathAndQuery: string, rawBody: string): boolean {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
  const t = parts.t;
  const v1 = parts.v1;
  if (!/^\d{1,12}$/.test(t ?? '') || !/^[0-9a-f]{64}$/.test(v1 ?? '')) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > WINDOW_SEC) return false;
  const expected = createHmac('sha256', KEY).update(`${t}.POST ${pathAndQuery}\n${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

const app = express();
app.post('/api/agent', express.raw({ type: 'application/json', limit: '64kb' }), async (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verify(req.header('x-db-signature'), req.originalUrl, rawBody)) {
    return res.status(401).json({ error: 'bad signature' });
  }
  const { conversationId, message } = JSON.parse(rawBody) as { v: 1; conversationId: string; message: string };
  const reply = await yourAgent.answer(conversationId, message); // your code
  res.json({ reply, messageId: null });
});
app.listen(3000);

# Flask. request.get_data() is the raw body, before any JSON parsing.
import hmac, hashlib, os, re, time
from flask import Flask, request, jsonify

KEY = os.environ["DEEPBLOCKER_SIGNING_KEY"].encode()
WINDOW_SEC = 300
app = Flask(__name__)

def verify(header: str | None, path_and_query: str, raw_body: bytes) -> bool:
    if not header:
        return False
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not re.fullmatch(r"\d{1,12}", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(int(time.time()) - int(t)) > WINDOW_SEC:
        return False
    payload = f"{t}.POST {path_and_query}\n".encode() + raw_body
    expected = hmac.new(KEY, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

@app.post("/api/agent")
def agent():
    raw = request.get_data()
    path_and_query = request.full_path if request.query_string else request.path
    if not verify(request.headers.get("x-db-signature"), path_and_query, raw):
        return jsonify(error="bad signature"), 401
    body = request.get_json(force=True)
    reply = your_agent.answer(body["conversationId"], body["message"])  # your code
    return jsonify(reply=reply, messageId=None)