# iglooKey Events

iglooworks sends webhook notifications when a recipient claims a token and when a recipient unlocks a lock with it.

All webhook requests are signed — see [Webhook Security](/works/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 only to the iglooworks account that created the iglooKey access.

## 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 | ISO 8601. Equals `claimedAt` for iglooKey Claimed events and `unlockedAt` for iglooKey Used events. |
| proxyTransportMethod | integer | Always `1` |

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.000Z",
      "proxyTransportMethod": 1
    },
    "product": {
      "type": 1
    }
  }
}
```

`type` is always `1000` for iglooKey Claimed events. `product` carries only `type`; it has no `id`.

| 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-16T08:12:03.000Z",
      "proxyTransportMethod": 1
    },
    "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 |

## 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. `date` equals `unlockedAt`, so it does not show when the event was sent.