Webhooks
Get a signed POST to your URL the moment a lead lands, a deal moves or a contact replies, with retries, a delivery
A webhook calls your URL the moment something happens in the workspace, so you don’t have to keep asking. Every delivery is signed, and a failed delivery is retried for
Create a webhook#
In Settings#
Owners and admins can add one
- In Workspace, open Settings → Integrations & API.
- Under Webhooks, choose New webhook.
- Paste your URL, pick Which events?, and choose Add webhook.
- Copy the signing secret it shows you, and put it
in your receiver.
The test button beside a webhook sends a signed ping event to your URL right away, and shows what
Over the API#
Anyone with a key or a connection that has the webhooks scope
curl -X POST https://workspace.brokerandagent.com/api/public/v1/webhooks \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/broker-agent", "events": ["lead.created", "transaction.status_changed"] }'urlmust behttps.eventsdefaults to["*"], every event. See all the events.- The answer includes the signing secret (
whsec_…). Over the API, this is the only time it’s shown, sostore it now.
Each person can hold 30 webhooks, and a workspace 200 in all. Only the person who made a webhook can change its URL or events. Owners and admins can turn anyone’s off or on,
What a delivery looks like#
Every delivery is a JSON POST with
{
"id": "evt_…",
"type": "lead.created",
"createdAt": "2026-10-02T15:00:00.000Z",
"workspace": "tnt_…",
"data": { "contact": { "id": "ct_…", "name": "Dana Reyes" } }
}The contact, task, appointment, transaction and envelope objects in data are the same objects the
What a webhook sees#
A webhook sees what the person who made it sees. An agent’s webhook carries that agent’s own book; a personal calendar block reaches only its maker’s and attendees’ webhooks. A webhook made with an API key or an app ends when the key is revoked or the app is disconnected. A suspended
Answer quickly#
Answer with any 2xx within 10 seconds. Anything else, including a redirect, counts as a failure. Do slow work after you’ve answered,
Retries and switching off#
We retry a failed delivery with backoff and a little jitter: after about 1 minute, then 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and a day twice. That’s nine attempts over
- Deliveries can arrive more than once. Deduplicate on the
X-BA-Deliveryheader. - Answer
410 Goneto retire a webhook for good: we stop at once andswitch it off. - After ten deliveries in a row run out of retries, the webhook
switches itself off.
When a webhook switches itself off, we email the person who made it and leave them a notice in the app, with your endpoint’s last answer and when. Fix the endpoint, then choose Turn back on in Settings, or send PATCH /webhooks/{id} with { "active": true }. Turning it back on
Deliveries and Resend#
Open Deliveries and signing secret under a webhook in Settings to see its last 30 days of deliveries: the event, what it was about, your endpoint’s answer and when. Resend sends any one of them again, as a new delivery, while the webhook is on. The log and Resend are in Settings only, not
The signing secret#
- In Settings, only the person who made a webhook can reveal its secret, after a quick sign-in check. Everyone else sees a hint, like
whsec_••••7Qk2. - Rotating a secret keeps the old one working for 24 hours. The maker, or an owner or admin, can rotate it; an owner or admin never sees
the new one.
See Verify signatures for checking deliveries and rotating
Related#
Something missing or wrong? Email support@brokerandagent.com and