Вебхуки

Вебхук — це Kept, що надсилає запит на обрану вами адресу, коли щось відбувається в локації: додано річ, переміщено або видалено в Кошик, зафіксовано показник, наступив термін нагадування. Кожен POST підписано, щоб ваш сервер міг перевірити, що він від Kept. Він містить ідентифікатори та назви полів, що змінилися, але ніколи їх значень: щоб отримати саму річ, ваш сервер запитує її через API за власним токеном.

Власники та адміністратори керують вебхуками локації в Налаштування локації → Вебхуки: Додати вебхук, адресу та події, які він обробляє. Налаштування → Зв’язки перелічує вебхуки, якими ви керуєте у своїх локаціях.

Події

Подія	Надсилається коли
thing.created	Додано річ
thing.updated	Річ змінено
thing.moved	Річ переміщено
thing.trashed	Річ потрапила в Кошик
thing.restored	Річ відновлено з Кошика
thing.lifecycle_changed	Стан речі змінився, наприклад, втрачено або продано
reading.logged	Зафіксовано показник лічильника
reminder.due	Наступив термін нагадування

Кожне корисне навантаження має однакові поля:

{
  "id": "evt_…",
  "event": "thing.updated",
  "occurred_at": "2026-10-03T09:12:44.000Z",
  "location_id": "…",
  "entity": { "type": "thing", "id": "…" },
  "changed_fields": ["…"],
  "actor": { "type": "user", "id": "…" }
}

entity.type — це thing, reading або reminder (webhook для тесту); changed_fields називає поля, що змінились при записі, і порожнє для нагадування; actor.type — це user, token або system.

Надіслати тест надсилає подію ping, яка відправляється один раз і не повторюється, і показує статус, з яким відповів ваш сервер: найшвидший спосіб перевірити нову адресу.

Перевірка підпису

Кожна доставка містить заголовок Kept-Signature:

Kept-Signature: t=1792700000,v1=<64 hex characters>

t — це час підпису (секунди Unix). v1 — це HMAC-SHA256, підписаний секретом вебхука, від <t>.<body>: мітка часу, крапка, потім точне тіло запиту. Ваш сервер обчислює той самий HMAC, порівнює його з v1 за постійного часу, і відхиляє старий t (більше п’яти хвилин, скажімо). Діалог секрета має готовий фрагмент Перевірити доставку (Node.js).

Секрет

Підписовий секрет показується один раз, при створенні вебхука: скопіюйте його тоді. Kept зберігає його запечатаним для підпису і ніколи більше не показує. Втрачено? Новий секрет створює інший; поточний перестає працювати миттєво, тому доставки не пройдуть перевірку, поки ваш сервер не отримає новий.

Доставки

Доставки кожного вебхука перелічує останні 30 днів, найновіші зверху: один рядок на доставку, зі станом, статусом, яким відповів ваш сервер (або без нього), та скільки спроб знадобилося.

• Очікує надсилання: в черзі.
• Доставлено: ваш сервер відповів зі статусом 2xx.
• Не вдалося, пробує знову: будь-яка інша відповідь, відсутність відповіді за 10 секунд, або перенаправлення (Kept не слідує за перенаправленнями). Kept пробує знову.
• Припинено: 10 спроб за близько 24 години всі провалились.

Не більше 10 доставок за секунду виходять на локацію, щоб пакет змін не завалював ваш сервер.

Коли доставка призупиняється, вебхук позначається Не працює з цієї дати, і адміністратори екземпляра отримують сповіщення. Він продовжує надсилати; наступна успішна доставка знімає позначку.

Вебхук перемикається Вимкнено, коли власник або адміністратор вимикає його, або коли особа, що його створила, більше не є адміністратором локації. Видалення остаточне: Kept перестає надсилати на нього, а його доставки забуваються.

Ваш власний вебхук, для нагадувань

Окремо від вебхуків локації, Налаштування → Я → Сповіщення може додати вебхук як один із ваших власних каналів, поруч з email, push, ntfy, Telegram та Apprise (нагадування). Він отримує один POST на нагадування (reminder.due) з ідентифікаторами, видом нагадування, типом джерела та датою терміну, річчю, місцем або локацією, яку це стосується, та посиланням назад у Kept: без назв чи значень. Він підписаний тим самим способом, із секретом, показаним один раз.

Провалена відправка повторюється до 10 разів за близько 24 години; якщо жодна не пройшла, канал позначається Не працює з і Kept надішле вам email один раз. Тест надсилає один зараз. Можна мати до п’яти.

Адреси у вашій власній мережі

Kept відмовляється надсилати на приватні адреси (такі як 192.168.x.x), тому вебхук не можна спрямувати на маршрутизатор або інший сервіс у мережі сервера. Адміністратор екземпляра може дозволити їх у Адміністрування → Реєстрація (Дозволити приватні адреси), для приймача, який ви хостите самостійно, такого як Home Assistant. Той самий перемикач дозволяє постачальнику AI, імпорту Homebox та входу через OIDC достукати до цієї мережі, тому вмикайте його, знаючи, хто може їх додавати. Див. модель безпеки.