Webhooks overview

Webhooks are how Dolores tells your backend that an appointment changed — typically because the voice agent just booked one, confirmed one, or cancelled one on a live call. Instead of having to poll, you register an endpoint URL and Dolores delivers a signed HTTPS POST whenever a relevant event happens.

Mental model

Voice calls are real-time; your CRM updates don't have to be. Dolores has its own appointment ledger, so the agent can confirm a booking with the caller immediately, and your system receives the update moments later via webhook.

That means your webhook handler should be idempotent and tolerant of out-of-order delivery. Two appointment.confirmed events for the same appointment id shouldn't double-book; an appointment.cancelled followed by an appointment.created for the same id (which can happen during a reschedule flow) should land in the correct final state.

What we deliver

Dolores v1 emits appointment-status events only:

• appointment.created
• appointment.confirmed
• appointment.rescheduled
• appointment.cancelled
• appointment.failed

There are no customer.* or session.* events in v1. Customer state is yours to manage via the REST API (we'll add events later if there's demand). Session lifecycle isn't broadcast either — poll /v1/sessions if you need session listings.

See Event types for full payload examples.

What we don't do

• We don't deliver events synchronously. Your agent flow doesn't have to wait for your webhook handler to succeed before continuing.
• We don't store delivered payloads on your behalf — once you 2xx, we consider it your responsibility. Use GET /v1/events/{id} for forensic replay within 30 days.
• We don't deliver from a static IP range. Don't allowlist by source IP; verify the signature instead. See Signing.

Lifecycle of a webhook

1. Register an endpoint via POST /v1/webhook_endpoints or the Settings → Webhooks admin UI. Save the one-time signing secret.
2. Filter which events you want via event_filters (omit or empty array to receive all). Wildcards (appointment.*) are supported.
3. Receive deliveries as HTTPS POST to your URL, signed with Dolores-Signature.
4. Verify the signature, parse the event, do your work, return 2xx.
5. On non-2xx or timeout, Dolores retries with exponential backoff up to ~24 hours. See Retry behavior.