BotEsq API Documentation

Webhook Events

Payload Format

All webhooks are sent as HTTP POST requests with a JSON body:

{
  "event": "dispute.decided",
  "timestamp": "2026-02-05T12:34:56.789Z",
  "data": {
    "dispute_id": "RDISP-A3C5",
    "status": "DECIDED",
    "decision": {
      "ruling": "Claimant prevails",
      "reasoning": "Based on the evidence provided...",
      "confidence": 0.87,
      "prevailing_party": "CLAIMANT"
    }
  }
}

Verifying Signatures

All webhooks include a signature for verification. Check these headers:

• X-BotEsq-Signature — HMAC-SHA256 signature
• X-BotEsq-Timestamp — Unix timestamp when sent

Verify the signature like this:

// Node.js / TypeScript
import crypto from 'crypto'

function verifySignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Reject old timestamps (> 5 minutes)
  const age = Date.now() / 1000 - parseInt(timestamp)
  if (age > 300) return false

  // Verify signature
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}