Webhooks & events

Event catalog

All 27 webhook event types, what triggers them and which scope they need.

Every event uses the envelope. An endpoint receives only the types it lists (or ["*"]) and that its credential's scopes can read. Events are also listed by GET /v1/events for 30 days.

Leads#

`lead.created`#

A new lead (any channel), once per lead. needs_address true when it waits for an address. Spam and blocked website repeats are not leads; one that is later reopened as a live lead is announced then (within 30 days of the request).

Needs leads:read · data.object: Lead

`lead.touched`#

A repeat request folded into an existing lead (API, inbound, or a website request blocked as a repeat of an earlier one): data.touch is the new request.

Needs leads:read · data.object: Lead

`lead.updated`#

Status, hold or address change (archived, spam, reopened, held → converted, address added → converted).

Needs leads:read · data.object: Lead

`lead.mockup_ready`#

A website request form lead's instant preview step finished (sent once, after lead.created, never delaying it): data.object.mockup_status is ready, failed or skipped. It fires once the request's one preview is settled (or 30 minutes after the request), so data.object.assets.mockups and preview_looks list it (older leads may list up to 3). Image URLs are not in the payload: GET /v1/leads/{id} returns data.object.assets with 60-minute signed links. Origin type is always embed.

Needs leads:read · data.object: Lead

Clients#

`client.created`#

A new client.

Needs clients:read · data.object: Client

`client.updated`#

Name, email or phone changed, or a property was added, edited or removed or the primary property changed (previous_attributes.updated_fields: first_name, last_name, email, phone, properties, primary_property), or another client was merged into this one (updated_fields merged: its client.deleted names this client in merged_into). Coalesced per client, per origin and per minute, trailing edge: a webhook endpoint gets one delivery per window, sent at its end and showing the client as it is then. A recorded event is never changed: a later edit in the same minute is a new client.updated (updated_fields lists every field the window changed so far), so the events feed can list more than one per minute, and an earlier delivery not yet sent is cancelled (superseded) in favor of the new one.

Needs clients:read · data.object: Client

`client.deleted`#

A client was deleted: id and external refs only. merged_into is set when the contractor merged it into an existing client (re-point your records to that client).

Needs clients:read · data.object: ClientTombstone

Projects#

`project.created`#

A new project (from a lead with an address, or created in the app). A website request blocked as a repeat still gets its own project in the app: its lead is that request (status duplicate), announced as lead.touched on the earlier lead.

Needs projects:read · data.object: Project

`project.stage_changed`#

The pipeline stage changed (a move, a quote or approval, a saved measurement in the app, a deleted draft quote). data.stage_change is the transition at event time ({from, to, sequence}); trigger on data.stage_change.to, not on data.object.pipeline_stage (the current stage). previous_attributes.pipeline_stage equals stage_change.from.

Needs projects:read · data.object: Project