Webhooks

Webhooks let Breezy notify your systems when service request and interaction events happen. Webhook endpoint management requires a user token. Service API keys cannot create, update, rotate, delete, or list webhook endpoints. Open the Webhooks tab in Breezy to manage endpoint configuration from the dashboard.

Supported events

Event type	When it fires
`service_request.created`	A new service request is created.
`service_request.status_changed`	A service request status changes.
`service_request.booked`	A service request is booked through instant booking.
`interaction.completed`	A voice or chat interaction is finalized.

Management flow

Authenticate with a user JWT.
POST /integrations/webhooks with a name, HTTPS URL, and event types.
Store the returned signingSecret immediately. It is shown only once.
Verify every delivery using the breezy-signature header.
Rotate a signing secret when needed. Rotation immediately invalidates the old secret.

Local development URLs may use localhost, 127.0.0.1, or ::1. Production webhook URLs must use HTTPS.

Delivery format

Breezy sends POST requests with a JSON envelope:

{
  "id": "8d7f2a70-5b57-4c08-9e7d-8d6d52f517d2",
  "type": "service_request.created",
  "createdAt": "2026-06-17T18:00:00.000Z",
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "serviceRequestId": "sr_...",
    "referenceNumber": "SR-1001",
    "channel": "web_chat",
    "serviceNeeded": "Water heater repair",
    "customer": {
      "name": "Ava Customer",
      "phoneNumber": "+15555550123",
      "emailAddress": "ava@example.com"
    }
  }
}

Deliveries include these headers:

Header	Description
`breezy-event-id`	Event id.
`breezy-event-type`	Event type.
`breezy-delivery-id`	Stable delivery id for idempotency and support.
`breezy-timestamp`	ISO 8601 timestamp used in signature verification.
`breezy-signature`	HMAC signature in `v1=<hex>` format.

Webhook payloads include operational fields needed by integrations, but do not include raw transcripts.

Event data

service_request.created data can include:

{
  "serviceRequestId": "sr_...",
  "referenceNumber": "SR-1001",
  "channel": "web_chat",
  "leadSourceId": "lead_source_...",
  "conversationId": "conv_...",
  "serviceNeeded": "Water heater repair",
  "preferredTimeWindow": "Tomorrow morning",
  "serviceAddress": "123 Main St, Denver, CO 80202",
  "serviceAddressLine1": "123 Main St",
  "serviceAddressLine2": "Unit 4",
  "serviceCity": "Denver",
  "serviceState": "CO",
  "serviceZipCode": "80202",
  "jobTypeFreetext": "Water heater",
  "jobClass": "plumbing",
  "jobTypeId": "job_type_...",
  "availabilityWindows": [],
  "customFields": {},
  "onlineBookingFormId": "booking_form_...",
  "customer": {
    "name": "Ava Customer",
    "firstName": "Ava",
    "lastName": "Customer",
    "phoneNumber": "+15555550123",
    "emailAddress": "ava@example.com"
  }
}

service_request.status_changed data:

{
  "serviceRequestId": "sr_...",
  "channel": "web_chat",
  "leadSourceId": "lead_source_...",
  "previousStatus": "new",
  "newStatus": "in_progress"
}

service_request.booked data:

{
  "serviceRequestId": "sr_...",
  "referenceNumber": "SR-1001",
  "interactionId": "voice_call_...",
  "confirmedWindowStart": "2026-06-18T16:00:00.000Z",
  "confirmedWindowEnd": "2026-06-18T18:00:00.000Z",
  "providerAppointmentId": "appt_..."
}

interaction.completed data:

{
  "interactionId": "interaction_...",
  "channel": "voice",
  "conversationOutcome": "booked"
}

Fields with no value are omitted from data.

Signature verification

Compute the expected signature with HMAC-SHA256:

signed_payload = breezy_timestamp + "." + raw_request_body
signature = "v1=" + hmac_sha256(signing_secret, signed_payload)

Compare your expected signature to breezy-signature using a constant-time comparison. Reject requests with missing headers, invalid signatures, or stale timestamps according to your integration’s tolerance.

Retries and history

Breezy treats any non-2xx response as a failed delivery. Failed deliveries are retried up to 3 total attempts, then marked abandoned. Deliveries are at least once. Use breezy-delivery-id as your idempotency key because a delivery can be retried after network or persistence uncertainty. Use GET /integrations/webhooks/deliveries to inspect recent delivery status. Pass endpointId to filter history for one endpoint.

Guides

API Reference

Webhooks

Webhooks

Supported events

Management flow

Delivery format

Event data

Signature verification

Retries and history

​Webhooks

​Supported events

​Management flow

​Delivery format

​Event data

​Signature verification

​Retries and history

Webhooks

Supported events

Management flow

Delivery format

Event data

Signature verification

Retries and history