Docs

1) Get inbox code + key

Go to Add server and copy:

• Inbox code (Server ID)
• Inbox key (keep private)

2) Send an approval request

Your bot sends a POST to the ingest endpoint.

POST https://botvector.app/api/vector
Headers:
  content-type: application/json
  x-botvector-secret: <INBOX_KEY>

Body:
{
  "server_id": "<INBOX_CODE>",
  "bot_name": "DemoBot",
  "action_title": "Ban PlayerX",
  "context": "Aimbot signal: 0.92. Evidence: https://example.com/clip",
  "callback_url": "https://your-bot.example.com/botvector/callback"
}

Responses: 201 ok, 401 wrong key, 410 archived server, 429 rate limited.

3) Receive callbacks (execute loop)

When an admin approves or rejects, Botvector POSTs to your callback_url with:

• Headers: x-botvector-timestamp, x-botvector-signature, x-botvector-delivery-id
• Body: request_id, server_id, status, decided_at

4) Verify signatures

Signature is HMAC SHA-256 over "timestamp.rawBody" using your BOTVECTOR_CALLBACK_SECRET.

import crypto from "crypto";

export function verifyBotvectorSignature({ secret, timestamp, rawBody, signature }) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

import hmac, hashlib

def verify_botvector_signature(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    msg = timestamp.encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Troubleshooting

• Rotate keys in Manage servers if you suspect exposure.
• If callbacks fail, Botvector retries automatically. Use x-botvector-delivery-id for idempotency on your side.