# Webhook events

> Every Broker & Agent webhook event, when it fires and what its data carries.

Every event we can send, and what its `data` carries. Each delivery is a JSON `POST` with the same envelope: `id`, `type`, `createdAt`, `workspace` and `data`. See [Verify signatures](https://brokerandagent.com/developers/webhooks/verify) before trusting one.

| Event | Fires when |
|---|---|
| [`lead.created`](#lead-created) | A new lead landed |
| [`contact.created`](#contact-created) | A contact was added |
| [`contact.stage_changed`](#contact-stage-changed) | A contact moved pipeline stage |
| [`contact.tagged`](#contact-tagged) | Tags were added to a contact |
| [`contact.replied`](#contact-replied) | A contact replied |
| [`task.completed`](#task-completed) | A task was checked off |
| [`appointment.created`](#appointment-created) | An appointment was booked |
| [`transaction.created`](#transaction-created) | A deal was opened |
| [`transaction.status_changed`](#transaction-status-changed) | A deal changed status or column |
| [`envelope.sent`](#envelope-sent) | A document went out for signature |
| [`envelope.signed`](#envelope-signed) | A signer signed |
| [`envelope.completed`](#envelope-completed) | Everyone signed |
| [`envelope.declined`](#envelope-declined) | A signer declined |
| [`envelope.voided`](#envelope-voided) | The sender voided a request |

## lead.created

**A new lead landed.** A new inbound lead from any door: the website, lead email, the events API. Sent to every active subscription for `lead.created` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `contact` | [Contact](https://brokerandagent.com/developers/api/reference/objects#contact) |  |
| `source` | string | Where it came from (website, zillow, …), the contact's source. |
| `sourceLabel` | string | The source as a person reads it. |
| `message` | string or null |  |
| `property` | string or null | The listing or address the lead asked about. |

## contact.created

**A contact was added.** A contact added by any door. Bulk imports deliberately don't send it. Sent to every active subscription for `contact.created` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `contact` | [Contact](https://brokerandagent.com/developers/api/reference/objects#contact) |  |

## contact.stage_changed

**A contact moved pipeline stage.** A contact moved to another pipeline stage. Sent to every active subscription for `contact.stage_changed` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `contact` | [Contact](https://brokerandagent.com/developers/api/reference/objects#contact) |  |
| `from` | `new`, `engaged`, `qualified`, `touring`, `under-contract`, `closed`, `nurture`, `lost` |  |
| `to` | `new`, `engaged`, `qualified`, `touring`, `under-contract`, `closed`, `nurture`, `lost` |  |

## contact.tagged

**Tags were added to a contact.** Tags added to a contact. Removals and renames stay quiet. Sent to every active subscription for `contact.tagged` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `contact` | [Contact](https://brokerandagent.com/developers/api/reference/objects#contact) |  |
| `addedTags` | array of string |  |

## contact.replied

**A contact replied.** An inbound text or email from a contact. Sent to every active subscription for `contact.replied` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `contactId` | string |  |
| `channel` | `sms`, `email` |  |
| `preview` | string | The start of the message, 500 characters at most. |
| `subject` | string | An email's subject. |

## task.completed

**A task was checked off.** A task checked off. Sent to every active subscription for `task.completed` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `task` | [Task](https://brokerandagent.com/developers/api/reference/objects#task) |  |

## appointment.created

**An appointment was booked.** An appointment booked. Sent to every active subscription for `appointment.created` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `appointment` | [Appointment](https://brokerandagent.com/developers/api/reference/objects#appointment) |  |

## transaction.created

**A deal was opened.** A deal opened. Sent to every active subscription for `transaction.created` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `transaction` | [Transaction](https://brokerandagent.com/developers/api/reference/objects#transaction) |  |

## transaction.status_changed

**A deal changed status or column.** A deal changed status or board column. A move that changes nothing sends nothing. Sent to every active subscription for `transaction.status_changed` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `transaction` | [Transaction](https://brokerandagent.com/developers/api/reference/objects#transaction) |  |
| `from` | `active`, `pending-close`, `closed`, `fell-through` | The status before. |

## envelope.sent

**A document went out for signature.** A document went out for signature. Sent to every active subscription for `envelope.sent` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `envelope` | [Envelope](https://brokerandagent.com/developers/api/reference/objects#envelope) |  |
| `recipientId` | string | The signer this is about, when it's about one. |

## envelope.signed

**A signer signed.** One signer signed; `recipientId` says which. Sent to every active subscription for `envelope.signed` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `envelope` | [Envelope](https://brokerandagent.com/developers/api/reference/objects#envelope) |  |
| `recipientId` | string | The signer this is about, when it's about one. |

## envelope.completed

**Everyone signed.** The last signer signed and the executed copy is sealed (`finalDocumentId`, `finalSha256`). Sent to every active subscription for `envelope.completed` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `envelope` | [Envelope](https://brokerandagent.com/developers/api/reference/objects#envelope) |  |
| `recipientId` | string | The signer this is about, when it's about one. |

## envelope.declined

**A signer declined.** A signer declined, which closes the request. Sent to every active subscription for `envelope.declined` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `envelope` | [Envelope](https://brokerandagent.com/developers/api/reference/objects#envelope) |  |
| `recipientId` | string | The signer this is about, when it's about one. |
| `reason` | string or null | What the signer wrote, if anything. |

## envelope.voided

**The sender voided a request.** The sender voided the request. Sent to every active subscription for `envelope.voided` or `*` whose creator can see the record.

`data` carries:

| Field | Type | |
|---|---|---|
| `envelope` | [Envelope](https://brokerandagent.com/developers/api/reference/objects#envelope) |  |
| `recipientId` | string | The signer this is about, when it's about one. |

---

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