Webhooks

Caution

This feature can only be configured using a config.yaml file.

Tip

To include the clientName in your webhook payload, append client=YOUR_CLIENT_NAME to your URL parameters.

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:

Tip

You can have multiple webhooks for different urls and events.

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:

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

Available Events Updated

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.interaction.click	Triggered when the user clicks/taps 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

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"
     }
}