Webhooks

Receive real-time AICA events via HTTP webhooks to integrate with external systems such as Slack, Zapier, n8n, or your own backend services.

Overview

Webhooks allow your application to be notified when events occur in AICA, eliminating the need to poll the API. When an event fires, AICA sends an HTTP POST request to your configured URL with a JSON payload describing the event.

Available Events

Event	Description	Triggered When
record.completed	Call fully processed	Audio transcribed, analyzed, and scored
analysis.completed	Analysis results ready	AI analysis and scoring finished
alert.triggered	Alert rule fired	A record matched an alert condition
incident.created	Incident escalated	An alert triggered incident creation

Configuration

1. Navigate to Project Settings > Delivery > Webhooks.
2. Click Add Webhook.
3. Enter your endpoint URL (must be HTTPS).
4. Select the events you want to subscribe to.
5. Click Test to send a sample payload and verify connectivity.
6. Save the configuration.

Each project can have multiple webhook endpoints, and each endpoint can subscribe to any combination of events.

Payload Format

All webhook payloads follow the same envelope structure:

{
  "event": "analysis.completed",
  "timestamp": "2026-03-05T12:00:00Z",
  "data": {
    "recordId": "rec_a1b2c3d4",
    "projectId": "proj_abc123",
    "qualityScore": 85,
    "status": "completed"
  }
}

Event-Specific Payloads

record.completed

{
  "event": "record.completed",
  "timestamp": "2026-03-05T12:00:00Z",
  "data": {
    "recordId": "rec_a1b2c3d4",
    "projectId": "proj_abc123",
    "duration": 342,
    "agentName": "John Smith",
    "status": "completed"
  }
}

alert.triggered

{
  "event": "alert.triggered",
  "timestamp": "2026-03-05T12:05:00Z",
  "data": {
    "alertId": "alert_xyz789",
    "alertName": "Low Quality Alert",
    "recordId": "rec_a1b2c3d4",
    "projectId": "proj_abc123",
    "condition": "qualityScore < 60",
    "actualValue": 45
  }
}

Security

All webhook requests are signed with HMAC-SHA256 so you can verify they originated from AICA.

Signature Verification

Each request includes the X-AICA-Signature header containing the HMAC-SHA256 hex digest of the raw request body, computed with your webhook secret.

Verification example (Node.js):

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(body, 'utf8').digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Your webhook secret is available in Project Settings > Delivery > Webhooks next to each configured endpoint.

Important: Always use a timing-safe comparison to prevent timing attacks. Reject any request where the signature does not match.

Retry Policy

If your endpoint returns a non-2xx status code or the request times out (30-second timeout), AICA retries delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes

After three failed retries, the delivery is marked as failed. You can view and manually retry failed deliveries from Settings > Delivery Status.

Best Practices

• Return 200 quickly. Process the webhook payload asynchronously. Acknowledge receipt immediately and handle the business logic in a background job.
• Handle duplicates. In rare cases, the same event may be delivered more than once. Use the recordId and event combination as an idempotency key.
• Monitor delivery status. Check the delivery log periodically for failed webhooks and address endpoint issues promptly.
• Use HTTPS. Webhook URLs must use HTTPS. HTTP endpoints are rejected during configuration.