Webhooks

Kiosk can notify external services about certain events using webhooks. When enabled, Kiosk will send HTTP POST requests to your specified webhook URL(s) when these events occur.

Enabling Webhooks

Add webhook configuration to your config.yaml:

webhooks:
  - url: "https://your-webhook-endpoint.com"
    event: asset.new
    secret: "my_webhook_secret" # Optional secret for securing webhooks

Webhook Security

When a secret is provided, Kiosk will generate a SHA-256 HMAC signature using the webhook payload and include it in the X-Kiosk-Signature-256 header. This allows you to verify that webhook request came from your Kiosk instance, following the same validation pattern as GitHub webhooks.

To validate webhooks on your server, you should:

Get the signature from the X-Kiosk-Signature-256 header
Generate a HMAC hex digest using your secret and the raw request body
Compare the signatures using a constant-time comparison function

Available Events

Event	Description
`asset.new`	Triggered when a new asset is requested from Kiosk
`asset.prefetch`	Triggered when Kiosk prefetches an asset data from Immich
`asset.history.next`	Triggered when a history asset (next) is requested from Kiosk
`asset.history.previous`	Triggered when a history asset (previous) is requested from Kiosk
`cache.flushed`	Triggered when the cache is manually cleared
`user.navigation.custom`	Triggered when the user clicks/taps the custom navigation section in Kiosk
`user.webhook.trigger.info_overlay`	Triggered when the “trigger webhook” button is clicked in the asset details overlay
`user.like.info_overlay`	Triggered when the “like” button is clicked in the asset details overlay
`user.unlike.info_overlay`	Triggered when the “unlike” button is clicked in the asset details overlay
`user.hide.info_overlay`	Triggered when the “hide” button is clicked in the asset details overlay
`user.unhide.info_overlay`	Triggered when the “unhide” button is clicked in the asset details overlay
`asset.offline.new`	Triggered when a new asset is requested from Kiosk when using offline mode
`asset.offline.history.next`	Triggered when a history asset (next) is requested from Kiosk when using offline mode
`asset.offline.history.previous`	Triggered when a history asset (previous) is requested from Kiosk when using offline mode

Webhook Payload

Field	Type	Description
`event`	string	The type of event, e.g., “asset.new”.
`timestamp`	string (ISO)	The time the event occurred, in ISO 8601 format.
`deviceID`	string (UUID)	Unique identifier for the device.
`clientName`	string	Name of the client device.
`assetCount`	int	Number of assets related to the event.
`assets`	array	Array of asset objects.
`config`	object	Configuration options for the application.
`meta`	object	Metadata about the source and version of the system.

Example payload

{
  "event": "asset.new",
  "timestamp": "2024-11-19T11:03:07Z",
  "deviceID": "ed08beb1-6de7-4592-9827-078c3ad91ae4",
  "clientName": "dining-room-pi",
  "assetCount": 1,
  "assets": [
    {
      "id": "bb4ce63b-b80d-430f-ad37-5cfe243e08b1",
      "type": "IMAGE",
      "originalMimeType": "image/jpeg",
      "localDateTime": "2013-04-06T23:45:54Z"
      /* ... other properties omitted for brevity */
    }
  ],
  "config": {
    /* ... configuration fields omitted for brevity */
  },
  "meta": {
    "source": "immich-kiosk",
    "version": "0.13.1"
  }
}