Reference

Webhooks

Receive real-time notifications when events occur in your BotEsq account. Webhooks enable you to build responsive integrations without polling.

Overview

Webhooks are HTTP callbacks that notify your application when events occur. When an event happens (e.g., consultation completed), BotEsq sends an HTTP POST request to your configured endpoint with event details.

Coming Soon

Webhooks are currently in beta. Contact support to enable webhooks for your operator account.

Setting Up Webhooks

Log in to your operator dashboard
Navigate to Settings > Webhooks
Click "Add Endpoint"
Enter your webhook URL (must be HTTPS)
Select the events you want to receive
Copy the signing secret for verification

Webhook Format

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

json

{
  "event": "consultation.completed",
  "timestamp": "2024-01-15T14:30:00Z",
  "webhook_id": "wh_abc123...",
  "data": {
    // Event-specific payload
  }
}

Headers

Header	Description
Content-Type	application/json
X-BotEsq-Signature	HMAC-SHA256 signature for verification
X-BotEsq-Timestamp	Unix timestamp when webhook was sent
X-BotEsq-Webhook-ID	Unique webhook delivery ID

Signature Verification

Always verify webhook signatures to ensure requests are from BotEsq:

typescript

import { createHmac } from 'crypto';
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Check timestamp to prevent replay attacks
  const webhookTime = parseInt(timestamp);
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - webhookTime) > 300) {
    return false; // Reject webhooks older than 5 minutes
  }
 
  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
 
  // Constant-time comparison to prevent timing attacks
  return signature === `sha256=${expectedSignature}`;
}
 
// Express.js example
app.post('/webhooks/botesq', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-botesq-signature'];
  const timestamp = req.headers['x-botesq-timestamp'];
  const payload = req.body.toString();
 
  if (!verifyWebhookSignature(payload, signature, timestamp, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
 
  const event = JSON.parse(payload);
  // Handle the event...
 
  res.status(200).send('OK');
});

Available Events

consultation.completed

A consultation has been completed by an attorney

Example Payload

json

{
  "event": "consultation.completed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "consultation_id": "con_abc123...",
    "matter_id": "mat_xyz789...",
    "status": "completed",
    "attorney_id": "atty_def456...",
    "completed_at": "2024-01-15T14:30:00Z"
  }
}

document.analyzed

Document analysis has been completed

Example Payload

json

{
  "event": "document.analyzed",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "document_id": "doc_ghi789...",
    "matter_id": "mat_xyz789...",
    "status": "completed",
    "page_count": 15,
    "attorney_id": "atty_def456..."
  }
}

matter.status_changed

A matter status has changed

Example Payload

json

{
  "event": "matter.status_changed",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "matter_id": "mat_xyz789...",
    "previous_status": "pending_retainer",
    "new_status": "active"
  }
}

credits.low

Account credits have fallen below threshold

Example Payload

json

{
  "event": "credits.low",
  "timestamp": "2024-01-15T09:00:00Z",
  "data": {
    "operator_id": "op_abc123...",
    "credits_remaining": 5000,
    "threshold": 10000
  }
}

retainer.expiring

A retainer offer is about to expire

Example Payload

json

{
  "event": "retainer.expiring",
  "timestamp": "2024-01-15T08:00:00Z",
  "data": {
    "retainer_id": "ret_abc123...",
    "matter_id": "mat_xyz789...",
    "expires_at": "2024-01-16T08:00:00Z"
  }
}

Best Practices

Respond quickly (under 5 seconds) - Process webhooks asynchronously if needed
Return 2xx status - Any other status triggers retries
Handle duplicates - Use webhook_id for idempotency
Verify signatures - Always validate the X-BotEsq-Signature header
Log webhook_id - For debugging and support requests

Retry Policy

If your endpoint returns a non-2xx status or times out, BotEsq retries with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry (final)	24 hours

After 5 failed attempts, the webhook is marked as failed and will not be retried. You can manually retry failed webhooks from the dashboard.