From 70dcdebe94d6155be721de84c7fac93cadd9bc55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20=C5=81ucyszyn?= Date: Mon, 6 Jul 2026 19:18:10 +0200 Subject: [PATCH] Add unique ID field to webhook payloads for deduplication --- docs/source/webhooks/bell-button-pressed.rst | 5 ++++- docs/source/webhooks/device-battery-level-changed.rst | 5 ++++- docs/source/webhooks/device-connection-changed.rst | 5 ++++- docs/source/webhooks/device-settings-changed.rst | 5 ++++- docs/source/webhooks/lock-status-changed.rst | 5 ++++- docs/source/webhooks/overview.rst | 8 +++++++- 6 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/source/webhooks/bell-button-pressed.rst b/docs/source/webhooks/bell-button-pressed.rst index b5f4546..5d03462 100644 --- a/docs/source/webhooks/bell-button-pressed.rst +++ b/docs/source/webhooks/bell-button-pressed.rst @@ -14,6 +14,8 @@ Body +------------------------+---------------------------------------------+-----------------------------------------------------------+ | event | string | event name: "bell-button-pressed" | +------------------------+---------------------------------------------+-----------------------------------------------------------+ +| id | string | unique id of the webhook, used for deduplication | ++------------------------+---------------------------------------------+-----------------------------------------------------------+ | timestamp | datetime | exact time when the webhook was sent to the receiver | +------------------------+---------------------------------------------+-----------------------------------------------------------+ | userIdentity | string | receiver of the webhook (user identity) | @@ -39,8 +41,9 @@ Examples .. code-block:: js - { + { "event": "bell-button-pressed", + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "timestamp": "2024-12-13T07:36:36.9049417+00:00", "userIdentity": "", "data": { diff --git a/docs/source/webhooks/device-battery-level-changed.rst b/docs/source/webhooks/device-battery-level-changed.rst index 27bbb8a..e349b81 100644 --- a/docs/source/webhooks/device-battery-level-changed.rst +++ b/docs/source/webhooks/device-battery-level-changed.rst @@ -14,6 +14,8 @@ Body +------------------------+---------------------------------------------------+-----------------------------------------------------------+ | event | string | event name: "device-battery-level-changed" | +------------------------+---------------------------------------------------+-----------------------------------------------------------+ +| id | string | unique id of the webhook, used for deduplication | ++------------------------+---------------------------------------------------+-----------------------------------------------------------+ | timestamp | datetime | exact time when the webhook was sent to the receiver | +------------------------+---------------------------------------------------+-----------------------------------------------------------+ | userIdentity | string | receiver of the webhook (user identity) | @@ -43,8 +45,9 @@ Examples .. code-block:: js - { + { "event": "device-battery-level-changed", + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "timestamp": "2022-11-09T14:15:30.244Z", "userIdentity": "", "data": { diff --git a/docs/source/webhooks/device-connection-changed.rst b/docs/source/webhooks/device-connection-changed.rst index b47615a..c8cedce 100644 --- a/docs/source/webhooks/device-connection-changed.rst +++ b/docs/source/webhooks/device-connection-changed.rst @@ -14,6 +14,8 @@ Body +------------------------+------------------------------------------------+-----------------------------------------------------------+ | event | string | event name: "device-connection-changed" | +------------------------+------------------------------------------------+-----------------------------------------------------------+ +| id | string | unique id of the webhook, used for deduplication | ++------------------------+------------------------------------------------+-----------------------------------------------------------+ | timestamp | datetime | exact time when the webhook was sent to the receiver | +------------------------+------------------------------------------------+-----------------------------------------------------------+ | userIdentity | string | receiver of the webhook (user identity) | @@ -43,8 +45,9 @@ Examples .. code-block:: js - { + { "event": "device-connection-changed", + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "timestamp": "2022-11-09T14:15:30.244Z", "userIdentity": "", "data": { diff --git a/docs/source/webhooks/device-settings-changed.rst b/docs/source/webhooks/device-settings-changed.rst index 429a363..11ce751 100644 --- a/docs/source/webhooks/device-settings-changed.rst +++ b/docs/source/webhooks/device-settings-changed.rst @@ -15,6 +15,8 @@ Body +------------------------+------------------------------------------------+-----------------------------------------------------------+ | event | string | event name: "device-settings-changed" | +------------------------+------------------------------------------------+-----------------------------------------------------------+ +| id | string | unique id of the webhook, used for deduplication | ++------------------------+------------------------------------------------+-----------------------------------------------------------+ | timestamp | datetime | exact time when the webhook was sent to the receiver | +------------------------+------------------------------------------------+-----------------------------------------------------------+ | userIdentity | string | receiver of the webhook (user identity) | @@ -46,8 +48,9 @@ Examples .. code-block:: js - { + { "event": "device-settings-changed", + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "timestamp": "2022-11-09T14:15:30.244Z", "userIdentity": "", "data": { diff --git a/docs/source/webhooks/lock-status-changed.rst b/docs/source/webhooks/lock-status-changed.rst index 1f69330..665eb30 100644 --- a/docs/source/webhooks/lock-status-changed.rst +++ b/docs/source/webhooks/lock-status-changed.rst @@ -15,6 +15,8 @@ Body +------------------------+---------------------------------------------+-----------------------------------------------------------+ | event | string | event name: "lock-status-changed" | +------------------------+---------------------------------------------+-----------------------------------------------------------+ +| id | string | unique id of the webhook, used for deduplication | ++------------------------+---------------------------------------------+-----------------------------------------------------------+ | timestamp | datetime | exact time when the webhook was sent to the receiver | +------------------------+---------------------------------------------+-----------------------------------------------------------+ | userIdentity | string | receiver of the webhook (user identity) | @@ -46,8 +48,9 @@ Examples .. code-block:: js - { + { "event": "lock-status-changed", + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "timestamp": "2022-11-09T14:15:30.244Z", "userIdentity": "", "data": { diff --git a/docs/source/webhooks/overview.rst b/docs/source/webhooks/overview.rst index 61d8139..0bd7780 100644 --- a/docs/source/webhooks/overview.rst +++ b/docs/source/webhooks/overview.rst @@ -15,9 +15,15 @@ Once the webhook URL for your integration is registered, the Tedee system will s We send webhooks for all connected users separately, which allows you to receive device changes for each user independently. -**Example**: Imagine there is the Tedee lock that has been opened. Suppose the Tedee lock has more than one user - for example, an owner and admin, where both of them are connected to your integration. +**Example**: Imagine there is the Tedee lock that has been opened. Suppose the Tedee lock has more than one user - for example, an owner and admin, where both of them are connected to your integration. In that case, two webhook notifications will be received on your webhook URL. The 'Data' object in the webhook notifications is identical, but user identities differ. +**Deduplication** + +Every webhook payload contains a unique ``id`` field. The same value is also sent as the ``Idempotency-Key`` HTTP request header on the POST request. +If a delivery is retried (for example after a network issue or a non-2xx response from your endpoint), the retry carries the same ``id`` and the same ``Idempotency-Key`` header value as the original attempt. +Use either of these to detect and discard duplicate deliveries on your side. + **Available webhooks** - `Device battery level changed `_