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 carrydata.lead.project.*events carrydata.project.unit.*events carrydata.unitanddata.project.lead.note_addedcarriesdata.leadIdanddata.note.lead.communication_loggedcarriesdata.leadIdanddata.communication.
Verifying the signature
Always verify the signature before trusting a payload. Anyone who knows your URL can hit it; only FlowEstate has the secret.POST /webhooks/subscriptions and is shown only once. If you lose it, delete the subscription and create a new one.
Acknowledging
Return any2xx 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:
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, andX-FlowEstate-Source tells you which one it came through:
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.
Preventing loops
When you write to FlowEstate via this REST API, the resulting webhook fans out withX-FlowEstate-Source: api. If your receiver also writes back into FlowEstate, drop events with source api to avoid an infinite loop.
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.