Send BuildersBridge events to your own systems
When a lead is created, an invoice is paid or an estimate is approved, BuildersBridge POSTs a signed JSON payload to an HTTPS endpoint you control. This page documents exactly what that request looks like, including the parts most vendors leave out.
- Method
- POST, JSON body
- Events
- lead.created, invoice.paid, estimate.approved
- Signature header
- x-buildersbridge-signature
- Algorithm
- HMAC-SHA256, hex digest of the raw body
- Timeout
- 5 seconds
- Retries
- None — see below
- Setup
- Dashboard → Settings → Integrations
Verifying the signature
Set a signing secret in Settings and every request carries an x-buildersbridge-signature header. The value is an HMAC-SHA256 digest, hex encoded, computed over the exact raw request body using your secret as the key.
Compute the same digest on your side and compare. Compare using a constant-time function rather than string equality, and compute it over the raw body before any JSON parsing — a parse-and-re-serialise round trip changes the bytes and the signatures will not match.
There are no retries
This is the part worth reading twice. BuildersBridge attempts delivery once, with a five-second timeout. If your endpoint is down, slow, or returns an error, the event is dropped. It is not queued, and it will not be attempted again.
That is a deliberate trade rather than an oversight: the webhook fires after the business action has already been written, and a retry queue that blocks or delays a builder saving an invoice would be the wrong failure. But it does mean webhooks here are a notification mechanism, not a guaranteed-delivery integration bus.
The practical consequence for anything that matters: acknowledge fast, do the real work asynchronously, and reconcile periodically against CSV export rather than assuming you received every event. If your endpoint takes longer than five seconds to respond, you have already missed it.
Setting up an endpoint
Your endpoint needs to accept a POST over HTTPS, read the raw body, verify the signature, respond quickly, and be idempotent. Idempotency matters less here than on a retrying system, but it costs nothing and protects you if delivery behaviour changes.
Add the endpoint URL and a signing secret in Dashboard → Settings → Integrations, then trigger a real event — create a test lead — to see the payload shape. A request bin is the fastest way to inspect the first delivery before you write any handling code.
Events fire independently of email
Notification emails have per-organisation preferences; webhooks do not. Turning off the new-lead email does not turn off lead.created. Estimate approval has no email toggle at all and is webhook-only.
So the event stream is the same three events for everyone with an endpoint configured, regardless of what the notification settings say.
Questions
- What header carries the signature?
- x-buildersbridge-signature. It contains an HMAC-SHA256 hex digest of the raw request body, keyed with the signing secret you set in Settings.
- What happens if my endpoint is down?
- The event is lost. There is one delivery attempt with a five-second timeout and no retry queue. Reconcile against CSV export if you need certainty that you have every record.
- Can I choose which events to receive?
- Not currently. An endpoint receives all three events, and your handler should switch on the event type in the payload.
- Does it work over plain HTTP?
- Use HTTPS. The payload carries business data and the signature only proves origin, not confidentiality.
- How do I rotate the signing secret?
- Change it in Dashboard → Settings → Integrations. Because there is a single secret and no overlap period, update your endpoint to accept the new secret at the same time, or expect to drop the events sent in between.
Connect it on any plan
Calendar feeds, Zapier and webhooks are included on every plan — no add-on, no integration fee.