Webhook events

This is the index of every event Cooledge can send to a webhook. When something happens in your business, Cooledge makes a signed HTTP POST to your subscription URL with the event as JSON. Each event has its own page with the exact fields it carries. This page covers what every event has in common and links to each event's page.

If you are setting up a subscription for the first time, start with the webhooks guide. It covers managing subscriptions in the portal, verifying the signature, retries and replay. This page is the catalogue of what you can subscribe to.

The event envelope

Every event body is a single JSON object. It always starts with the same five envelope fields, then the fields specific to that event type are merged in alongside them. The envelope is what lets you route and dedupe an event without knowing its type.

Field	What it is
`version`	The envelope version. Always the string `"v1"` today.
`event_type`	The event name, for example `"customer.created"`. Switch on this to decide how to handle the body.
`event_id`	A stable UUID for this event. It is the same across every redelivery and replay, so it is your dedupe key. It is also sent as the `X-Cooledge-Event-Id` header.
`business_id`	The Cooledge business the event belongs to.
`occurred_at`	An ISO 8601 timestamp for when the event happened.

A body looks like this. The five envelope fields are always present, and the rest depends on the event_type (the trailing fields below stand in for whatever that specific event carries):

{
  "version": "v1",
  "event_type": "customer.created",
  "event_id": "3b1c0e2a-7d44-4e91-9a2c-1f0b8e6d5a23",
  "business_id": "a7f3c9d1-2e84-4b6f-8c01-5d9e2a1f7b30",
  "occurred_at": "2026-06-17T03:21:44.512Z",

  "...": "event-specific fields are merged in here"
}

The exact event-specific fields live on each event's own page, linked in the table below. New fields may be added to any payload over time, so ignore fields you do not recognise rather than failing on them.

Delivery and deduping

Cooledge delivers at least once. The same event can reach you more than once, because a retry can land after your endpoint already processed the first attempt, or because you replayed it from the portal. So your handler must be idempotent.

Dedupe on event_id. The same value is on the X-Cooledge-Event-Id header, and it is stable across every redelivery and replay of the same event. Store the event ids you have already processed and skip any you have seen before.

The signature scheme, the retry and dead-letter behaviour and replaying a delivery all live in the webhooks guide. They are the same for every event type, so they are documented once there rather than repeated here.

The events

The event types are grouped by the record they are about. Each links to its own page with the full payload shape.

Customers

Event	What it means	Page
`customer.created`	A new customer was added.	customer.created
`customer.updated`	An existing customer's details changed.	customer.updated

Leads

Event	What it means	Page
`lead.created`	A new lead came in.	lead.created
`lead.updated`	An existing lead's details or status changed.	lead.updated
`lead.converted`	A lead became an active opportunity, with its first quote or job.	lead.converted
`lead.won`	A lead was won, with a quote accepted or paid or a first invoice paid.	lead.won

Quotes

Event	What it means	Page
`quote.sent`	A quote was sent to a customer.	quote.sent
`quote.accepted`	A customer accepted a quote.	quote.accepted
`quote.paid`	A quote with a deposit or upfront amount was paid.	quote.paid

Invoices

Event	What it means	Page
`invoice.sent`	An invoice was sent to a customer.	invoice.sent
`invoice.paid`	An invoice was paid.	invoice.paid

Jobs

Event	What it means	Page
`job.completed`	A job was marked complete.	job.completed

Bookings

Event	What it means	Page
`booking.created`	A booking or scheduled visit was created.	booking.created

Messages

Event	What it means	Page
`message.received`	A customer or an unknown sender texted or emailed the business.	message.received
`message.sent`	Someone on the team sent a text or email from Messages, including a draft.	message.sent

Message events

Message events carry the words of your customers' messages, so they have one extra rule. Through the API, creating a subscription that includes message.received or message.sent needs the messages:read scope as well as webhooks:manage. So does an update that leaves either event on the subscription, rotating its secret or deleting it. Without messages:read the request is a 403. Subscriptions the account owner creates in the portal under Settings → Integrations → Webhooks need no scope. A key that loses messages:read later keeps the subscriptions it already has.

An update to any subscription only applies if the subscription has not changed since the request read it. If two updates race, the one that loses answers 409. Read the subscription again and retry.

Two delivery notes. message.received waits until an email's attachments or a picture message's media are stored. It is sent on a delivery run every few minutes, so expect it usually within a few minutes, not in real time. message.sent is best effort: in rare cases an event is lost and is not retried. Each page has the detail.

Where to go next

Webhooks covers subscriptions, signature verification, retries and replay.
Authentication covers the scope list, including webhooks:manage for the subscription API and messages:read for message events.
The API changelog records new event types and other additive changes to the contract.