> For the complete documentation index, see [llms.txt](https://api-docs.everreal.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.everreal.co/webhooks.md).

# Webhooks

EverReal sends a request to your registered URL at each event that you choose.

## Rules

* To list, register, edit or delete webhooks, the [access token](https://api-docs.everreal.co/key-concepts.md#access-token) needs both [scopes](https://api-docs.everreal.co/key-concepts.md#scope) `company_user` and `company_admin`. A company admin has both. A token without them answers `403`.
* A [webhook](https://api-docs.everreal.co/key-concepts.md#webhook) belongs to the [partner](https://api-docs.everreal.co/key-concepts.md#partner) of the request. You can list, edit and delete only the webhooks of your own partner. A webhook id of another partner answers `404`.
* The `url` must be an https url. Another url answers `400` with `api.externalIntegrations.webhook.urlNotHttps`.
* The `type` must be one of the event names in [Event Types](#event-types). Another name answers `400` with `api.externalIntegrations.webhook.unknownEvent`.
* Webhooks that are already stored stay as they are.
* Delivery is partner-wide: every webhook of the partner for an event name gets that event, with the full payload. An event of any [company](https://api-docs.everreal.co/key-concepts.md#company) of your partner goes to every webhook of the partner for that event. For most events, `data.companyId` tells you the company.
* The same `url` cannot be registered twice for one event.

## Delivery

* EverReal sends each event as an HTTP `POST` with a JSON body to your `url`.
* Every event has the same envelope: `uuid` (the id of the event), `operation` (the event name, for example `LISTING_CREATED`), `subdomain` (the [subdomain](https://api-docs.everreal.co/key-concepts.md#subdomain) of your partner), `language`, `createdAt` and `data`. `data` is the payload that the page of each event shows. Some event pages show only `data`.
* EverReal sends each event once. There is no retry, and EverReal does not read your answer. If your system cannot take the event, the event is lost. Read the current data with the reporting API to catch up.
* The request has no signature. Keep your `url` secret, and check important data with the reporting API before you act on it.

## List Webhooks

<mark style="color:blue;">`GET`</mark> `https://{subdomain}.everreal.co/api/external-integrations/webhooks`

Lists all webhooks of your partner.

#### Headers

| Name          | Type   | Description                                                               |
| ------------- | ------ | ------------------------------------------------------------------------- |
| Authorization | string | [Bearer Token](https://api-docs.everreal.co/key-concepts.md#access-token) |

{% tabs %}
{% tab title="200 " %}

```javascript
[
    {
        "id": "d32d5912-4496-4398-814e-a734ccadb615",
        "type": "LISTING_CREATED",
        "partnerId": "76dccab0-652e-4543-802c-7c701c046579",
        "companyId": "2f0c6d1a-8b34-4a57-9e10-6c7d3b5a9f21",
        "connectedByUserId": "0b6f1c2e-4a7d-4c1e-9d55-3a1f6e2b7c10",
        "url": "https://example.com/webhooks/everreal",
        "createdAt": "2020-09-30T10:07:28.052Z",
        "updatedAt": "2020-09-30T10:07:28.052Z",
        "deletedAt": null
    }
]
```

{% endtab %}

{% tab title="403 User not authorized" %}

```javascript
{
    "code": "server_error",
    "statusCode": 403
}
```

{% endtab %}
{% endtabs %}

## Register a new Webhook

<mark style="color:green;">`POST`</mark> `https://{subdomain}.everreal.co/api/external-integrations/webhooks`

Registers a new webhook for your partner.

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

#### Request Body

| Name         | Type   | Description                                                                                                 |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
| Body Request | object | <p><code>{</code><br><code>"type":"string",</code><br><code>"url":"string"</code><br><code>}</code><br></p> |

`type` is an event name from [Event Types](#event-types). `url` is an https url.

{% tabs %}
{% tab title="200 " %}

```javascript
// Response Header
{
"Location": "d32d5912-4496-4398-814e-a734ccadb615"
}
```

{% endtab %}

{% tab title="400 " %}
The `url` is not an https url (`api.externalIntegrations.webhook.urlNotHttps`). Or the `type` is not a known event name (`api.externalIntegrations.webhook.unknownEvent`).
{% endtab %}
{% endtabs %}

## Edit a Webhook

<mark style="color:orange;">`PATCH`</mark> `https://{subdomain}.everreal.co/api/external-integrations/webhooks/:id`

Changes the `type` or the `url` of a webhook of your partner. The same rules as for a new webhook apply. A `PATCH` cannot change the id, the partner, the [company](https://api-docs.everreal.co/key-concepts.md#company) or the connected [user](https://api-docs.everreal.co/key-concepts.md#user-and-member).

#### Path Parameters

| Name | Type   | Description                     |
| ---- | ------ | ------------------------------- |
| :id  | string | Webhook id provided by EverReal |

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

{% tabs %}
{% tab title="200 " %}

{% endtab %}

{% tab title="400 " %}
The new `url` is not an https url. Or the new `type` is not a known event name.
{% endtab %}

{% tab title="404 " %}
The webhook does not exist, or belongs to another partner.
{% endtab %}
{% endtabs %}

## Delete a Webhook

<mark style="color:red;">`DELETE`</mark> `https://{subdomain}.everreal.co/api/external-integrations/webhooks/:id`

Deletes a webhook of your partner by its unique ID. A webhook id of another partner answers `404`.

#### Path Parameters

| Name | Type   | Description                     |
| ---- | ------ | ------------------------------- |
| :id  | string | Webhook id provided by EverReal |

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

{% tabs %}
{% tab title="204 " %}

{% endtab %}
{% endtabs %}

## Event Types

Below is a list of all events available in EverReal. Only these names are accepted as `type`.

{% hint style="info" %}
Each event type has its own payload. The sub pages of Webhooks show the payload of each event type.
{% endhint %}

| Events                                                                              | List of available actions                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Listing**](https://api-docs.everreal.co/key-concepts.md#listing) **events**      | `LISTING_CREATED`, `LISTING_UPDATED`, `LISTING_ARCHIVED`, `LISTING_ACTIVATED`, `LISTING_DEACTIVATED`, `LISTING_PUBLISHED_TO_CHANNEL`, `LISTING_UNPUBLISHED_FROM_CHANNEL`                                                                                                                                                                     |
| [**Candidates**](https://api-docs.everreal.co/key-concepts.md#candidate) **events** | `CANDIDATE_PARSED`, `LISTING_CANDIDATE_APPLIED`                                                                                                                                                                                                                                                                                              |
| **Scheduling events**                                                               | `LISTING_CANDIDATE_SCHEDULE_INVITED_VIEWING`, `LISTING_CANDIDATE_SCHEDULE_NEW_TIMESLOTS_REQUESTED`, `LISTING_CANDIDATE_SCHEDULE_TIMESLOT_BOOKED_ADMIN`, `LISTING_CANDIDATE_SCHEDULE_TIMESLOT_BOOKED_CANDIDATE`, `LISTING_CANDIDATE_SCHEDULE_TIMESLOT_BOOKING_REMOVED_ADMIN`, `LISTING_CANDIDATE_SCHEDULE_TIMESLOT_BOOKING_REMOVED_CANDIDATE` |
| **Contracting events**                                                              | `LISTING_CONTRACT_FLOW_STARTED`, `LISTING_CONTRACT_FLOW_WITHDRAWN`, `LISTING_CONTRACT_FLOW_PARTIALLY_SIGNED`, `LISTING_CONTRACT_FLOW_SIGNED`, `CONTRACT_FLOW_COMPLETED_WITH_PLUGINS`, `TENANT_CREATED`                                                                                                                                       |
| [**Owner**](https://api-docs.everreal.co/key-concepts.md#owner) **events**          | `OWNER_CREATED`, `OWNER_UPDATED`, `OWNER_DELETED`                                                                                                                                                                                                                                                                                            |
| [**Properties**](https://api-docs.everreal.co/key-concepts.md#property) **events**  | `PROPERTY_CREATED`, `PROPERTY_UPDATED`, `PROPERTY_DELETED`                                                                                                                                                                                                                                                                                   |
| [**Units**](https://api-docs.everreal.co/key-concepts.md#unit) **events**           | `UNIT_CREATED`, `UNIT_UPDATED`, `UNIT_DELETED`                                                                                                                                                                                                                                                                                               |
| [**Protocol**](https://api-docs.everreal.co/key-concepts.md#protocol) **events**    | `PROTOCOL_COMPLETED`                                                                                                                                                                                                                                                                                                                         |

Example: create a webhook.

{% tabs %}
{% tab title="cURL" %}

```
curl --location --request POST 'https://{subdomain}.everreal.co/api/external-integrations/webhooks' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type":"LISTING_CANDIDATE_APPLIED",
    "url":"https://<your_domain>/<your_path>"
}'
```

{% endtab %}
{% endtabs %}
