Skip to main content
FlowEstate sends webhooks when leads, projects, or units change. Subscribers register a target URL and an event type; FlowEstate fans out signed POST requests with a JSON body. To manage subscriptions programmatically (create, list, delete), see the Webhooks API reference. This page covers what your receiver needs to do once a subscription is in place.

Headers

Every delivery includes:

Body

data is event-specific:
  • lead.* events carry data.lead.
  • project.* events carry data.project.
  • unit.* events carry data.unit and data.project.
  • lead.note_added carries data.leadId and data.note.
  • lead.communication_logged carries data.leadId and data.communication.
For the full list of events see Enums.

Verifying the signature

Always verify the signature before trusting a payload. Anyone who knows your URL can hit it; only FlowEstate has the secret.
Sign the raw bytes of the request body. Re-serializing the parsed JSON will produce a different signature because key order, whitespace, and number formatting may differ.
The secret comes from the response of POST /webhooks/subscriptions and is shown only once. If you lose it, delete the subscription and create a new one.

Acknowledging

Return any 2xx HTTP status to acknowledge receipt. FlowEstate doesn’t read the response body — empty 200 is fine. If your handler does heavy work (calling other APIs, writing to a slow database), acknowledge first, process later:
The delivery timeout is a few seconds — slow handlers cause spurious retries.

Retry policy

Failed deliveries (network error, timeout, or HTTP ≥ 400) are retried with this backoff: After five failed attempts the delivery is marked failed and won’t be retried again. The X-FlowEstate-Delivery header stays the same across retries — use it as your idempotency key when processing.

Where lead events come from

A lead can enter FlowEstate through several doors, and X-FlowEstate-Source tells you which one it came through:
Expect more traffic than before. Until this release, only leads created through the REST API, the dashboard, and bulk import emitted lead.created and lead.assigned. Leads arriving through an inbound webhook, Meta lead ads, or WhatsApp were silent — your endpoint never heard about them.They now emit the same events as every other channel, tagged X-FlowEstate-Source: system. If your organization takes most of its leads through those channels, your delivery volume will rise accordingly — and on the Free plan it may now reach the monthly allowance below. Nothing about the payload changed; there is simply more of it.
lead.assigned also fires when a repeated contact is routed. Posting a contact that already exists merges into the existing lead (Deduplication and merge), and if that lead had no owner yet, the round robin assigns it — so a merge can produce lead.assigned without a preceding lead.created. Treat the two events as independent. A merge emits no lead.updated. Enrichment is currently silent on every channel.

Monthly event allowance

Outbound deliveries are metered per calendar month, per organization: One event fanned out to three endpoints counts as three deliveries.
Hitting the allowance is silent. Once an organization is over its monthly count, further events are dropped before dispatch: no delivery is attempted, no retry is scheduled, and your receiver has no way to tell the difference between “nothing happened” and “the allowance ran out”. The events are not queued and are not replayed when the next month starts.If your integration must not miss events, either keep the organization on a plan with no allowance, or reconcile periodically against GET /leads rather than trusting the stream alone.

Preventing loops

When you write to FlowEstate via this REST API, the resulting webhook fans out with X-FlowEstate-Source: api. If your receiver also writes back into FlowEstate, drop events with source api to avoid an infinite loop.
The other source values:
  • ui — change made by a user in the FlowEstate dashboard, including bulk import.
  • system — change made without a human in the loop: a lead arriving through an inbound webhook, Meta lead ads, or WhatsApp, plus internal workers such as assignments and automations.
  • api — change made through this REST API (your own writes, partner platforms).
Filter on api only. Dropping system as well would discard exactly the inbound leads you most likely want to react to.