# Webhooks

Webhooks allow the Reelables Platform to proactively push events to your system in near real time, so you do not have to poll the API. When a subscribed event occurs, we send an HTTP `POST` request to a URL you provide, with a JSON body describing the event.

Please contact [Reelables Support](mailto:support@reelables.com) to get webhooks set up.

## Delivery format

Every webhook request shares a common envelope:
- `eventId`: a unique identifier for this event delivery.
- `eventAt`: the ISO 8601 timestamp at which the event was generated.
- `eventBody`: the event-specific payload. The `eventType` field within `eventBody` identifies the type of event.

## Authentication

The delivery of webhook events can be secured using one of three authentication methods. This authenticates Reelables to *your* endpoint (i.e. it applies to the outbound requests we send to you) and is agreed when your webhook is configured:

- **No authentication (`NONE`)**: events are delivered without any authentication. Recommended for testing only.
- **API key (`API_KEY`)**: a static API key that we include in a request header on every delivery. The header name and key value are agreed when your webhook is set up.
- **OAuth 2.0 (`OAUTH`)**: we obtain a short-lived access token from your OAuth token endpoint using the Client Credentials flow, and include it as a `Bearer` token in the `Authorization` header of each delivery. The token is refreshed automatically before it expires.

## Event types

There are four event types.

### `ASSET_SPACE` — asset entered / exited a Space

Emitted when a tracked `Asset` enters or leaves a `Space`. The `eventType` is `asset.enteredSpace` or `asset.exitedSpace`. The enter and exit events for the same visit share an `episodeId`; exit events additionally include an `exitedAt` timestamp.

```json
{
  "eventId": "ba0a2088-0041-f73c-879a-64de41cb28d2",
  "eventAt": "2026-04-15T20:38:05.103Z",
  "eventBody": {
    "episodeType": "ASSET_SPACE",
    "eventType": "asset.enteredSpace",
    "episodeId": "90e3d37d-dd09-4e66-9322-9a065461a314",
    "enteredAt": "2026-04-15T20:35:51.000Z",
    "assetId": "cWCwcHb8cXeWsHQ6o99MwQ",
    "assetName": "An Asset Name",
    "labelId": "841239917",
    "spaceId": "aFnXPecbnQyDPbs3tCRZyh",
    "spaceName": "A Space Name",
    "facilityId": "b536becb-ff45-4aca-b106-a4c0b3b1a52e",
    "facilityName": "A Facility Name",
    "coordinate": {
      "latitude": 51.5014241,
      "longitude": -0.14192321,
      "accuracy": 42
    },
    "address": {
      "road": "Buckingham Palace Road",
      "city": "London",
      "county": "Greater London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "United Kingdom"
    }
  }
}
```

```json
{
  "eventId": "c1e032b8-1982-4bca-9107-c6ae6466a27f",
  "eventAt": "2026-04-20T14:29:05.631Z",
  "eventBody": {
    "episodeType": "ASSET_SPACE",
    "eventType": "asset.exitedSpace",
    "episodeId": "90e3d37d-dd09-4e66-9322-9a065461a314",
    "enteredAt": "2026-04-15T20:35:51.000Z",
    "exitedAt": "2026-04-20T14:12:13.000Z",
    "assetId": "cWCwcHb8cXeWsHQ6o99MwQ",
    "assetName": "An Asset Name",
    "labelId": "841239917",
    "spaceId": "aFnXPecbnQyDPbs3tCRZyh",
    "spaceName": "A Space Name",
    "facilityId": "b536becb-ff45-4aca-b106-a4c0b3b1a52e",
    "facilityName": "A Facility Name",
    "coordinate": {
      "latitude": 51.5014241,
      "longitude": -0.14192321,
      "accuracy": 42
    },
    "address": {
      "road": "Buckingham Palace Road",
      "city": "London",
      "county": "Greater London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "United Kingdom"
    }
  }
}
```

### `ASSET_FACILITY` — asset entered / exited a Facility

Emitted when a tracked `Asset` enters or leaves a `Facility`. The `eventType` is `asset.enteredFacility` or `asset.exitedFacility`. As with Space events, the enter and exit events for the same visit share an `episodeId`, and exit events additionally include an `exitedAt` timestamp.

```json
{
  "eventId": "eb6647a8-4b71-48e3-ad9c-42214aaad75c",
  "eventAt": "2026-05-15T22:38:05.103Z",
  "eventBody": {
    "episodeType": "ASSET_FACILITY",
    "eventType": "asset.enteredFacility",
    "episodeId": "d23c8c3d-e454-4c31-911b-c8e25b2bde6f",
    "enteredAt": "2026-05-15T20:35:51.000Z",
    "assetId": "cWCwcHb8cXeWsHQ6o99MwQ",
    "assetName": "An Asset Name",
    "labelId": "841239917",
    "facilityId": "b536becb-ff45-4aca-b106-a4c0b3b1a52e",
    "facilityName": "A Facility Name",
    "coordinate": {
      "latitude": 51.5014241,
      "longitude": -0.14192321,
      "accuracy": 42
    },
    "address": {
      "road": "Buckingham Palace Road",
      "city": "London",
      "county": "Greater London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "United Kingdom"
    }
  }
}
```

```json
{
  "eventId": "aec65582-99df-4806-b191-7bd7efa14933",
  "eventAt": "2026-05-16T09:23:21.103Z",
  "eventBody": {
    "episodeType": "ASSET_FACILITY",
    "eventType": "asset.exitedFacility",
    "episodeId": "d23c8c3d-e454-4c31-911b-c8e25b2bde6f",
    "enteredAt": "2026-05-15T20:35:51.000Z",
    "exitedAt": "2026-05-16T09:21:45.103Z",
    "assetId": "cWCwcHb8cXeWsHQ6o99MwQ",
    "assetName": "An Asset Name",
    "labelId": "841239917",
    "facilityId": "b536becb-ff45-4aca-b106-a4c0b3b1a52e",
    "facilityName": "A Facility Name",
    "coordinate": {
      "latitude": 51.5014241,
      "longitude": -0.14192321,
      "accuracy": 42
    },
    "address": {
      "road": "Buckingham Palace Road",
      "city": "London",
      "county": "Greater London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "United Kingdom"
    }
  }
}
```

### `OBSERVATION` — point-in-time asset observation

Emitted when an `Asset` is observed. Reports the location of the `Asset` at `seenAt` and, where available, a `temperature` reading.

```json
{
  "eventId": "209f0aa9-b6dd-496d-b250-84a92ebfc506",
  "eventAt": "2026-04-20T08:19:38.607Z",
  "eventBody": {
    "eventType": "OBSERVATION",
    "seenAt": "2026-04-20T08:19:04.000Z",
    "workspaceId": "2ca827f2-0910-4cee-a86f-9eb700e611d1",
    "assetId": "cWCwcHb8cXeWsHQ6o99MwQ",
    "assetName": "An Asset Name",
    "labelId": "841239917",
    "coordinate": {
      "latitude": 51.5014241,
      "longitude": -0.14192321,
      "accuracy": 42
    },
    "address": {
      "road": "Buckingham Palace Road",
      "city": "London",
      "county": "Greater London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "temperature": {
      "degreesCelsius": 25.5,
      "accuracy": 0.5
    }
  }
}
```

### `LABEL_ACTIVATION` — label activated

Emitted when a `Label` is activated and associated with an `Asset`. The `activation.method` indicates how the `Label` was activated (`PRINTER` or `TAP`).

```json
{
  "eventId": "050bb8ee-1bca-4377-be0d-63eea15048f9",
  "eventAt": "2026-04-29T12:36:18.000Z",
  "eventBody": {
    "eventType": "LABEL_ACTIVATION",
    "activatedAt": "2026-04-29T12:34:02.000Z",
    "workspaceId": "2ca827f2-0910-4cee-a86f-9eb700e611d1",
    "assetId": "cWCwcHb8cXeWsHQ6o99MwQ",
    "assetName": "An Asset Name",
    "labelId": "841239917",
    "activation": {
      "method": "PRINTER"
    }
  }
}
```