# 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.

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:

```bash
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](https://brokerandagent.com/developers/webhooks/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](https://brokerandagent.com/developers/api/reference/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](https://brokerandagent.com/developers/webhooks/verify) for checking deliveries and rotating without dropping events.

## Related

- [Webhook events](https://brokerandagent.com/developers/webhooks/events)
- [Verify signatures](https://brokerandagent.com/developers/webhooks/verify)

---

Source: https://brokerandagent.com/developers/webhooks
