Webhooks

Receive real-time HTTP notifications when events occur in your FrontDeskOS workspace.

Overview

Webhooks allow you to receive real-time notifications about events in your FrontDeskOS workspace. When an event occurs (e.g., a call completes, an appointment is booked), FrontDeskOS sends an HTTP POST request to your configured endpoint with the event data.

Creating a Webhook

Create webhooks through the dashboard or programmatically via the admin tools:

Creating a webhooktypescript

const result = await mcp.callTool("frontdesk_create_webhook", {
  url: "https://yourapp.com/webhooks/frontdesk",
  events: ["call.completed", "appointment.booked", "lead.created"],
  secret: "whsec_your_signing_secret"
});

Available Events

Parameter	Type	Description
`call.started`	`event`	An incoming or outgoing call has started.
`call.completed`	`event`	A call has ended. Includes summary and transcript.
`call.missed`	`event`	A call was missed (no answer, caller hung up).
`call.voicemail`	`event`	A voicemail was left.
`appointment.booked`	`event`	A new appointment was created.
`appointment.cancelled`	`event`	An appointment was cancelled.
`appointment.rescheduled`	`event`	An appointment was rescheduled.
`appointment.reminder`	`event`	An appointment reminder was sent.
`lead.created`	`event`	A new lead was captured.
`lead.converted`	`event`	A lead was marked as converted.
`lead.scored`	`event`	A lead's score was updated.

Payload Format

Webhook payload

200 OK

{
  "id": "evt_abc123",
  "type": "call.completed",
  "workspace_id": "ws_your_workspace",
  "created_at": "2025-01-15T09:30:00Z",
  "data": {
    "call_id": "call_01abc",
    "direction": "inbound",
    "caller_name": "John Smith",
    "caller_phone": "+1-555-0123",
    "duration_seconds": 142,
    "summary": "Scheduled annual check-up for Jan 22nd",
    "sentiment": "positive"
  }
}

Verifying Signatures

Every webhook request includes a signature in the X-FrontDesk-Signature header. Always verify this signature to ensure the request is authentic.

Verifying webhooks (Node.js)typescript

import crypto from "crypto";

function verifyWebhook(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(`sha256=${expected}`)
  );
}

// In your webhook handler
app.post("/webhooks/frontdesk", (req, res) => {
  const signature = req.headers["x-frontdesk-signature"] as string;
  const isValid = verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET);

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

  // Process the event
  const event = req.body;
  switch (event.type) {
    case "call.completed":
      handleCallCompleted(event.data);
      break;
    case "appointment.booked":
      handleAppointmentBooked(event.data);
      break;
  }

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

Webhook Reliability

FrontDeskOS retries failed webhook deliveries up to 5 times with exponential backoff. Your endpoint should respond with a 2xx status code within 30 seconds. If all retries fail, the webhook is marked as failed and an alert is sent to workspace admins.

Testing Webhooks

Use the webhook testing tool in the FrontDeskOS dashboard to send test events to your endpoint. You can also use the test API key to trigger events in sandbox mode without affecting production data.