Webhooks API

Register webhook endpoints to receive real-time event notifications from Boltcall.

Webhooks let your application react to Boltcall events in real time — new leads, completed calls, booked appointments, and more — without polling the API. Boltcall sends an HTTP POST request to your endpoint each time a subscribed event occurs.

For a UI-based setup guide, see Integrations → Webhooks.

Events

Each webhook subscription listens to a single trigger event:

Event	Description
new_lead	A new lead was captured from a call, SMS, or form
missed_call	An inbound call was not answered by the agent
appointment_booked	An appointment was scheduled by the agent
call_completed	A call ended — payload includes transcript and recording URLs
review_received	A new review was received

Payload structure

Every webhook payload follows the same structure:

Example payload

{
  "event": "call_completed",
  "timestamp": "2025-03-20T09:17:22Z",
  "data": {
    "id": "call_xyz789",
    "agent_id": "agent_abc123",
    "direction": "inbound",
    "caller": "[phone]",
    "duration_seconds": 142,
    "status": "completed",
    "sentiment": "positive",
    "summary": "Caller requested appointment for Friday.",
    "recording_url": "https://api.boltcall.org/v1/calls/call_xyz789/recording"
  }
}

The data object contains the full resource that triggered the event (lead, call, appointment, etc.).

Signature verification

Boltcall signs every webhook request with an X-Boltcall-Signature header so you can verify the payload came from Boltcall and was not tampered with.

The signature is an HMAC-SHA256 hex digest computed from the raw request body using the webhook’s secret as the key.

Always verify the signature before processing a webhook payload. Skipping verification exposes your endpoint to forged requests.

Node.js

import crypto from 'crypto';

function verifyBoltcallSignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

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

// Express.js example
app.post('/hooks/boltcall', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-boltcall-signature'];
  const secret = process.env.BOLTCALL_WEBHOOK_SECRET;

  if (!verifyBoltcallSignature(req.body, secret, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const payload = JSON.parse(req.body);
  console.log('Verified event:', payload.event);

  res.sendStatus(200);
});

Use express.raw() (not express.json()) to preserve the raw request body for signature verification. Parsing the body first changes the byte sequence and causes verification to fail.

---

List webhooks

Returns all webhook endpoints registered in your workspace.

cURL

curl https://api.boltcall.org/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "wh_001",
      "name": "Lead notification",
      "url": "https://yourapp.com/hooks/boltcall",
      "trigger_event": "new_lead",
      "is_active": true,
      "created_at": "2025-02-10T12:00:00Z"
    }
  ]
}

---

Register a webhook

Creates a new webhook subscription.

name · string

Optional display name for the webhook (e.g. "Zapier Lead Notification"). For your reference only.

url · string · required

The HTTPS endpoint URL that Boltcall will POST events to. Must use HTTPS.

trigger_event · string · required

The event type to subscribe to. See the events table for accepted values.

The secret is returned in full only at creation time. Copy and store it immediately in a secure location (e.g. your environment variables). You cannot retrieve it again from the API.

cURL

curl -X POST https://api.boltcall.org/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New lead alert",
    "url": "https://yourapp.com/hooks/boltcall",
    "trigger_event": "new_lead"
  }'

Response

{
  "id": "wh_002",
  "name": "New lead alert",
  "url": "https://yourapp.com/hooks/boltcall",
  "trigger_event": "new_lead",
  "is_active": true,
  "secret": "whsec_abc123...",
  "created_at": "2025-03-20T16:00:00Z"
}

---

Delete a webhook

Removes a webhook subscription. Boltcall will stop sending events to the registered URL immediately.

Path parameter

webhook_id · string · required

The ID of the webhook to delete.

cURL

curl -X DELETE https://api.boltcall.org/v1/webhooks/wh_002 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{ "deleted": true }

Retry behavior

Boltcall does not automatically retry failed webhook deliveries. If your endpoint returns a non-2xx status code or times out, the delivery is logged as failed. You can view delivery history in Dashboard → Integrations → Webhooks and use the test/replay feature to manually re-send a payload after resolving the issue.

Your endpoint should respond with 200 OK as quickly as possible. Process the payload asynchronously (e.g. push to a queue) rather than doing heavy work synchronously during the HTTP request.