# iglooKey Events

igloohome sends webhook notifications when a recipient claims a token and when a recipient unlocks a lock with it. See [iglooKey](/home/iglookey) for how tokens are created and shared.

All webhook requests are signed — see [Webhook Security](/home/webhook-security) for how to validate them.

## Delivery

Each event is sent as an HTTP `POST` to your registered webhook URL with `Content-Type: application/json` and an `x-igloocompany-sha256` signature header.

Events are sent to:

- The account that owns the iglooKey token.
- Apps the owner has connected through OAuth. See [Partner Account](/home/partner-account).

## Event Types

| Event Type | Number Mapping |
| --- | --- |
| iglooKey Claimed | 1000 |
| iglooKey Used | 1001 |

Every event shares these fields:

| Field | Type | Description |
| --- | --- | --- |
| id | string | Unique event ID (UUID) |
| type | integer | Event type number |
| data | object | Event-specific fields |
| date | string | When the webhook was sent, in ISO 8601. This is not the claim or unlock time. |
| proxyTransportMethod | integer | Always `0` |

All timestamps are ISO 8601 strings in UTC with milliseconds (e.g. `2025-09-15T10:30:45.000Z`).

## iglooKey Claimed Event

Sent once, when a recipient first claims an iglooKey token. It is not sent when:

- The recipient claims a token that is already claimed.
- The recipient claims an expired token.
- The recipient claims a token whose access window has ended.

```json
{
  "payload": {
    "event": {
      "id": "3f6c2a9e-8b41-4d7a-9e15-2c7d4b8a6f01",
      "type": 1000,
      "data": {
        "tokenId": "lnk_abc123def456ghi789jkl012mno345",
        "claimedAt": "2025-09-15T10:30:45.000Z"
      },
      "date": "2025-09-15T10:30:45.318Z",
      "proxyTransportMethod": 0
    }
  }
}
```

`type` is always `1000` for iglooKey Claimed events. This event has no `product` object.

| Field | Type | Description |
| --- | --- | --- |
| tokenId | string | The iglooKey token |
| claimedAt | string | When the token was claimed |

## iglooKey Used Event

Sent each time a recipient unlocks a lock with an iglooKey token. Each event covers one lock.

- **Online unlock:** Sent when the unlock completes while the recipient's phone is online.
- **Offline unlock:** Sent when the recipient's phone is back online and reports the unlock. The event can arrive well after the unlock.

This example is an offline unlock reported about 95 minutes after it happened:

```json
{
  "payload": {
    "event": {
      "id": "9a4e7c12-5d3b-4f86-b2a0-71e8c6d93f45",
      "type": 1001,
      "data": {
        "tokenId": "lnk_abc123def456ghi789jkl012mno345",
        "bluetoothId": "IGP1092b1e66",
        "unlockedAt": "2025-09-16T08:12:03.000Z",
        "reportedAt": "2025-09-16T09:47:20.000Z"
      },
      "date": "2025-09-16T09:47:20.540Z",
      "proxyTransportMethod": 0
    },
    "product": {
      "id": "IGP1092b1e66",
      "type": 1
    }
  }
}
```

`type` is always `1001` for iglooKey Used events. `product.id` is the Bluetooth ID of the unlocked device.

| Field | Type | Description |
| --- | --- | --- |
| tokenId | string | The iglooKey token |
| bluetoothId | string | Bluetooth ID of the unlocked device |
| unlockedAt | string | When the unlock happened |
| reportedAt | string | When the server received the unlock |

**Product Type**

| Product Type | Number Mapping |
| --- | --- |
| Lock | 1 |
| Keypad (`bluetoothId` starts with `EK`) | 3 |

## Handling Events

- **Ordering:** Events are not guaranteed to arrive in order.
- **Offline delay:** For offline unlocks, `reportedAt` can be much later than `unlockedAt`. Use `unlockedAt` for when access happened.