Webhook Management API

Webhooks let you receive real-time notifications when events happen in Empfio — a new lead is captured, a booking is created, a conversation is escalated. Instead of polling the API, your server receives a POST request with the event data.

Setup via dashboard

The easiest way to manage webhooks:

1. Go to Settings → Integrations → Webhooks
2. Click Add webhook
3. Enter your HTTPS endpoint URL
4. Select which events to subscribe to
5. Save — Empfio sends a test ping to verify the URL

Inbound webhook endpoints

These are the endpoints where Empfio receives events from external services:

Agent events

POST /api/v1/webhooks/agent-event

Receives events from the LangGraph agent service. Used internally — the agent calls this endpoint to report lead creation, status updates, booking requests, and escalations.

Event types: new_lead, status_update, booking_request, message_logged, escalation.

This endpoint is authenticated via an internal Bearer token (INTERNAL_AUTH_TOKEN in your environment configuration).

Cal.com events

POST /api/v1/webhooks/calcom

Receives webhook events from Cal.com when bookings are created, cancelled, or rescheduled.

Supported trigger events:

• BOOKING_CREATED — a new booking was made in Cal.com
• BOOKING_CANCELLED — a booking was cancelled
• BOOKING_RESCHEDULED — a booking was moved to a different time

Cal.com webhook signatures are verified using the CALCOM_WEBHOOK_SECRET if configured.

Outbound webhook payload

When you register a webhook URL, Empfio sends POST requests with this envelope:

{
  "event": "booking.created",
  "timestamp": "2026-03-07T10:30:00Z",
  "organization_id": "550e8400-...",
  "data": { ... }
}

See Webhook Events for the complete list of events and their data payloads.

Security

Each outbound webhook request includes an X-Empfio-Signature header — an HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

To verify a webhook:

1. Read the raw request body
2. Compute HMAC-SHA256(body, your_webhook_secret)
3. Compare the result with the X-Empfio-Signature header value

Retries

If your endpoint returns a non-2xx response or times out (10 seconds), Empfio retries with exponential backoff — up to 3 attempts over 30 minutes. After all retries fail, the event is logged as failed.

Event deduplication

Empfio includes deduplication logic for agent events. If the same event is received twice within 60 seconds, the duplicate is discarded and a {"status": "duplicate"} response is returned.