# 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**](/real-time-occupancy/webhooks-overview/human-detections.md), [**Traffic**](/real-time-occupancy/webhooks-overview/human-traffic.md), [**Floor Occupancy**](/real-time-occupancy/webhooks-overview/floor-occupancy.md), [**Room Occupancy**](/real-time-occupancy/webhooks-overview/room-occupancy.md), [**Zone Occupancy**](/real-time-occupancy/webhooks-overview/zone-occupancy.md)**,** [**Motion**](/real-time-occupancy/webhooks-overview/motion-detection.md)**, and** [**No Motion**](/real-time-occupancy/webhooks-overview/no-motion-detection.md) 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](/real-time-occupancy/webhooks-overview/human-detections.md)

* 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](/real-time-occupancy/webhooks-overview/human-traffic.md)

* 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](/real-time-occupancy/webhooks-overview/floor-occupancy.md)

* Event Type: `FLOOR_OCCUPANCY`
* Description: Receive updates on the number of occupants detected by the [presence sensor](https://docs.butlr.io/real-time-occupancy/pages/tyUDwu57k07Re6pSyyJL#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)](/real-time-occupancy/webhooks-overview/floor-occupancy/floor-occupancy.md)

* 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](/real-time-occupancy/webhooks-overview/room-occupancy.md)

* Event Type: `ROOM_OCCUPANCY`
* Description: Receive updates on the number of occupants detected by the [presence sensor](https://docs.butlr.io/real-time-occupancy/pages/tyUDwu57k07Re6pSyyJL#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)](/real-time-occupancy/webhooks-overview/room-occupancy/floor-occupancy.md)

* 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](/real-time-occupancy/webhooks-overview/zone-occupancy.md)

* Event Type: `ZONE_OCCUPANCY`
* Description: Receive updates on the number of occupants detected by the [presence sensor](https://docs.butlr.io/real-time-occupancy/pages/tyUDwu57k07Re6pSyyJL#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)](/real-time-occupancy/webhooks-overview/zone-occupancy/floor-occupancy.md)

* 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](/real-time-occupancy/webhooks-overview/motion-detection.md) 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](/real-time-occupancy/webhooks-overview/no-motion-detection.md) 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": { ... },
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.butlr.io/real-time-occupancy/webhooks-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.