Webhooks

Get a signed POST to your URL the moment a lead lands, a deal moves or a contact replies, with retries, a delivery log and Resend.

Updated Nov 11, 2026

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 almost three days.

Create a webhook#

In Settings#

Owners and admins can add one in the app.

  1. In Workspace, open Settings → Integrations & API.
  2. Under Webhooks, choose New webhook.
  3. Paste your URL, pick Which events?, and choose Add webhook.
  4. 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 your endpoint answered.

Over the API#

Anyone with a key or a connection that has the webhooks scope can create one:

Shell
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"] }'
  • url must be https.
  • events defaults 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, so store 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, or delete it.

What a delivery looks like#

Every delivery is a JSON POST with the same envelope:

JSON
{
  "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 API answers with.

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 workspace sends nothing.

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, from a queue.

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 about 2.7 days.

  • Deliveries can arrive more than once. Deduplicate on the X-BA-Delivery header.
  • Answer 410 Gone to retire a webhook for good: we stop at once and switch 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 forgives the failures.

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 in the API.

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 without dropping events.

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.