Webhooks Overview

Webhooks allow your application to receive real-time HTTP notifications when events occur in your Firetell workspace.

How Webhooks Work

1. You register a webhook URL via the Webhooks API or the Firetell Console
2. When an event occurs, Firetell sends an HTTP POST request to your URL
3. Your server processes the event and responds with a 200 status code

Webhook Payload Format

All webhook payloads follow this structure:

{
  "event": "call.completed",
  "timestamp": "2026-07-09T10:30:00Z",
  "workspaceId": "ws_abc123",
  "data": {
    "callId": "call_xyz789",
    "from": "+84901234567",
    "to": "+84909876543",
    "duration": 120,
    "status": "completed",
    "recordingUrl": "https://..."
  }
}

Event Types

Event	Description
call.ringing	An incoming call is ringing
call.answered	A call has been answered
call.completed	A call has ended
call.missed	A call was missed
recording.ready	A call recording is available
voicemail.received	A new voicemail was left
agent.status_changed	An agent changed their availability status

info

This is a preliminary list. The complete event catalog will be documented as the API implementation progresses.

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), Firetell will retry the delivery:

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

After 4 failed retries, the webhook is marked as failed and no further attempts are made.

Security

Validate incoming webhooks by checking the X-Firetell-Signature header. This header contains an HMAC-SHA256 signature of the request body using your webhook secret.

const crypto = require('crypto');

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

Best Practices

• Respond quickly — Return 200 immediately and process asynchronously
• Handle duplicates — Use the event ID for idempotency
• Use HTTPS — Always use HTTPS endpoints in production
• Validate signatures — Verify the X-Firetell-Signature header