Events Overview

SmartphoneKey publishes real-time events via AWS EventBridge whenever significant state changes occur in the access control system. Partners can subscribe to these events through webhooks to build integrations that react to changes as they happen — no polling required.

Event Sources

SmartphoneKey publishes events from two sources:

spk.api

Domain events from the B2C API — locks, users, hubs, cameras, temp keys, and Matter devices (e.g. LockCreated, KeyAdded, ResidentAdded, AccessibleLockAdded). The detail-type is the PascalCase event name, and the domain payload is wrapped under detail.data. This is the bulk of what most integrations consume. See the Event Catalog and Partner Webhooks for the full list.

spk.iot.shadow

Publishes Shadow Update events when an IoT hub device updates its AWS IoT Device Shadow. The event carries the thingName, version, desiredState, reportedState, and deltaState — the delta being non-empty when the device hasn't yet applied all desired configuration changes. Unlike spk.api events, the shadow fields live directly on detail (there is no detail.data wrapper).

Event Envelope

Every EventBridge event arrives wrapped in an AWS envelope:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "spk.iot.shadow",
  "detail-type": "Shadow Update",
  "time": "2024-03-15T10:30:00Z",
  "region": "eu-west-1",
  "account": "123456789012",
  "version": "0",
  "resources": [],
  "detail": {
    "partnerId": "<tenant-org-id>",
    "thingName": "<device-uuid>",
    "reportedState": "<stringified JSON of reported state>",
    "desiredState": "<stringified JSON of desired state>",
    "deltaState": "{}",
    "metadata": "<stringified IoT shadow metadata>",
    "version": 42
  }
}

The detail object is the event payload. See the Event Catalog for a full description of the fields.

Webhook Schema

We publish an OpenAPI 3.1 schema that describes the full webhook event payload structure. Use it to:

• Generate typed webhook handlers in any language via OpenAPI Generator
• Validate incoming payloads in your webhook endpoint
• Import into Postman, Insomnia, or other API tools for testing
• Browse the complete event type definitions with field-level documentation

Download: eventbridge-schemas.yaml

Subscribing to Events

Partners receive events through webhook subscriptions. When an event matches your subscription criteria, SmartphoneKey makes an HTTP POST to your registered endpoint with the event payload.

See the Partner Webhooks guide for configuration details and the Event Catalog for a complete reference of the event payload.