# Webhooks Overview

{% hint style="warning" %}
Users can subscribe only once to each event type (Detections, Traffic, Floor Occupancy, Room Occupancy, Zone Occupancy, Motion / No Motion detected).

Event ordering is not guaranteed. Prioritizing speed, we deliver events as received. Use event timestamps for ordering and implement idempotent processing to handle potential out-of-order or duplicate events.
{% endhint %}

## Butlr Webhooks

Butlr webhooks provide real-time updates on a variety of events, including [**Detections**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/human-detections), [**Traffic**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/human-traffic), [**Floor Occupancy**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/floor-occupancy), [**Room Occupancy**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/room-occupancy), [**Zone Occupancy**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/zone-occupancy)**,** [**Motion**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/motion-detection)**, and** [**No Motion**](https://docs.butlr.io/real-time-occupancy/webhooks-overview/no-motion-detection) detected. By subscribing to these webhooks, users gain automatic access to timely and accurate information without the need for manual checks or data requests.

Our webhooks deliver structured, easy-to-process data, enabling real-time notifications that support informed decision-making. This empowers users to react swiftly to changes, optimize physical spaces, and improve operational efficiency. With Butlr webhooks, you can confidently make data-driven decisions, maximizing the value of your real estate portfolio.

### Benefits

* Receive real-time updates on events and changes.
* Eliminate manual checks and data requests.
* Streamline data processing and stay updated.
* React quickly to changes and make data-driven decisions.

## Available Webhooks

### 1. [Detections](https://docs.butlr.io/real-time-occupancy/webhooks-overview/human-detections)

* Event Type: `DETECTIONS`
* Description: Receive coordinates (x, y) of detected people within a monitored area.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "DETECTIONS",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
  "data": {
    "local": [ [0.5625, 0.125], [0.75, 0.5625] ], // 2 detections
    "world": [ [85.694195, 27.829299], [87.439295, 28.577199]] // 2 detections
  }
}
```

### 2. [Traffic](https://docs.butlr.io/real-time-occupancy/webhooks-overview/human-traffic)

* Event Type: `TRAFFIC`
* Description: Receive updates on people entering or exiting a monitored area.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "TRAFFIC",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
  "data": {
    "in": 0,
    "out": 1
  }
}
```

### 3. [Floor Occupancy](https://docs.butlr.io/real-time-occupancy/webhooks-overview/floor-occupancy)

* Event Type: `FLOOR_OCCUPANCY`
* Description: Receive updates on the number of occupants detected by the [presence sensor](https://docs.butlr.io/spatial-metrics#id-2.-presence-mode) on a specific floor.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "FLOOR_OCCUPANCY",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
  "data": 25
}
```

### 3a. [Floor Occupancy (1-Minute)](https://docs.butlr.io/real-time-occupancy/webhooks-overview/floor-occupancy/floor-occupancy)

* Event Type: `FLOOR_OCCUPANCY_1MIN`
* **Description:** Same as Floor Occupancy, but aggregated and **smoothed at 1-minute** granularity.
* Payload Example: `Same as Floor Occupancy`

### 4. [Room Occupancy](https://docs.butlr.io/real-time-occupancy/webhooks-overview/room-occupancy)

* Event Type: `ROOM_OCCUPANCY`
* Description: Receive updates on the number of occupants detected by the [presence sensor](https://docs.butlr.io/spatial-metrics#id-2.-presence-mode) in a specific room.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "ROOM_OCCUPANCY",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
  "data": 4
}
```

### 4a. [Room Occupancy (1-Minute)](https://docs.butlr.io/real-time-occupancy/webhooks-overview/room-occupancy/floor-occupancy)

* Event Type: `ROOM_OCCUPANCY_1MIN`
* **Description:** Same as Room Occupancy, but aggregated and **smoothed at 1-minute** granularity.
* Payload Example: `Same as Room Occupancy`

### 5. [Zone Occupancy](https://docs.butlr.io/real-time-occupancy/webhooks-overview/zone-occupancy)

* Event Type: `ZONE_OCCUPANCY`
* Description: Receive updates on the number of occupants detected by the [presence sensor](https://docs.butlr.io/spatial-metrics#id-2.-presence-mode) in a specific zone.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "ZONE_OCCUPANCY",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
  "data": 1
}
```

### 5a. [Zone Occupancy (1-Minute)](https://docs.butlr.io/real-time-occupancy/webhooks-overview/zone-occupancy/floor-occupancy)

* Event Type: `ZONE_OCCUPANCY_1MIN`
* **Description:** Same as Zone Occupancy, but aggregated and **smoothed at 1-minute** granularity.
* Payload Example: `Same as Zone Occupancy`

### 6. [Motion](https://docs.butlr.io/real-time-occupancy/webhooks-overview/motion-detection) Detection

{% hint style="warning" %}
Available only with Heatic 2+ sensors.
{% endhint %}

* Event Type: `PIR_MOTION`
* Description: Event sent when motion is captured by the Heatic 2+ sensor, indicating activity detected in a room.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "PIR_MOTION",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
}
```

### 7. [No Motion](https://docs.butlr.io/real-time-occupancy/webhooks-overview/no-motion-detection) Detection

{% hint style="warning" %}
Available only with Heatic 2+ sensors.
{% endhint %}

* Event Type: `PIR_NO_MOTION`
* Description: Event sent when the Heatic 2+ sensor detects no motion, indicating no activity has occurred in a room.
* Payload Example:

```json
{
  "id": "event_xxx",
  "type": "PIR_NO_MOTION",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": { ... },
}
```