iglooKey Events

igloohome sends webhook notifications when a recipient claims a token and when a recipient unlocks a lock with it. See iglooKey for how tokens are created and shared.

All webhook requests are signed — see 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.

Event Types

Every event shares these fields:

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.

{
  "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.

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:

{
  "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.

Product Type

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.