API Integration and Webhooks

For developers: integrate FORAI with your custom systems using our REST API and real-time webhooks. This deep-dive covers authentication, key endpoints, webhook event types, payload structures, error handling, and rate limit management.

🎯 What You Will Learn

Generating and managing API keys with scoped permissions
Using the REST API to read call data, manage contacts, and trigger actions
Setting up webhooks for real-time event notifications
Implementing proper error handling, retry logic, and rate limit management

⚠️ Prerequisites

Developer experience with REST APIs and JSON
A server or serverless function to receive webhook events
FORAI account on Pro or Enterprise plan (API access requires Pro+)
Familiarity with HTTP authentication headers and webhook signatures

🚀 Step-by-Step Guide

Generate your API key

Navigate to Settings > API & Webhooks > API Keys. Click 'Generate New Key'. Choose the scope: Read Only (call data, contacts), Read/Write (all resources), or Custom (select specific permissions). Copy the key immediately -- it won't be shown again.

Settings - API Key Management

Authenticate your first API request

All API requests require the key in the Authorization header. Make a test request to GET /api/v1/calls to retrieve recent calls. A successful response returns a JSON array of call objects with full metadata.

Explore the key API endpoints

The API covers: /calls (list, get, search), /contacts (CRUD operations), /workflows (trigger, status), /analytics (metrics, reports), and /settings (read configuration). Each endpoint supports filtering, pagination, and field selection.

Set up a webhook endpoint

Create an HTTPS endpoint on your server to receive events. Register it at Settings > API & Webhooks > Webhooks > 'Add Endpoint'. Enter your URL and select which events to subscribe to. FORAI sends a test event to verify connectivity.

Webhook Configuration Panel

Subscribe to webhook events

Choose events: call.started, call.completed, call.transferred, appointment.booked, sms.sent, contact.created, workflow.triggered. Each event delivers a JSON payload with full context. Start with call.completed -- it's the most commonly used event.

Verify webhook signatures

Every webhook request includes an X-FORAI-Signature header containing an HMAC-SHA256 hash. Verify this signature against your webhook secret to ensure the event is authentic and hasn't been tampered with. Never process unverified webhooks.

Implement error handling and retries

Your endpoint must return a 200 status within 5 seconds. FORAI retries failed deliveries with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 12 hours. After 5 failures, the endpoint is flagged as unhealthy. Monitor the webhook delivery dashboard for failures.

Webhook Delivery Log

Manage API rate limits

The API allows 100 requests per minute (Pro) or 500 per minute (Enterprise). Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Implement client-side throttling and respect 429 responses with the Retry-After header.

🔗 Code Example

Webhook signature verification (Node.js)

import crypto from 'crypto';

// Verify FORAI webhook signature
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

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

// Express route handler
app.post('/webhooks/forai', (req, res) => {
  const signature = req.headers['x-forai-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.FORAI_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the event
  const { event, data } = req.body;
  console.log(`Received event: ${event}`, data);

  res.status(200).json({ received: true });
});

💡 Pro Tips

Use webhook events instead of polling the API wherever possible. Webhooks are real-time and don't count against your rate limit. Reserve API calls for on-demand queries and data exports.

Store your webhook secret in environment variables, never in code. Rotate the secret quarterly and update your endpoint configuration accordingly.

Implement idempotency using the event_id field included in every webhook payload. This prevents duplicate processing if FORAI retries a delivery that your server actually received.

Set up a dead-letter queue for webhook events your server fails to process. This prevents data loss during outages and lets you replay failed events after recovery.

⚠️ Important Warning

Always test your configuration with the built-in simulator before deploying to live callers. Changes to voice settings, routing rules, and workflows take effect within 60 seconds. Monitor the first 5-10 live calls after any change and revert immediately if you notice issues.

⚙️ Troubleshooting