Вебхуки: события DentOS для ваших систем

Вебхук — это запрос, который DentOS отправляет на адрес вашей системы, когда в клинике что-то произошло. Опрашивать API не нужно.

Подключение

1. «Настройки → API и вебхуки» → добавь адрес и отметь события.
2. Сохрани секрет подписи. По нему ваша система проверит, что запрос пришёл от DentOS.
3. Отправь проверочное событие ping и посмотри результат в журнале доставок.

В облачной версии адрес вебхука не может вести во внутреннюю сеть.

События

Событие	Когда
appointment.created	Новая запись
appointment.cancelled	Запись отменена
appointment.rescheduled	Запись перенесена
appointment.status_changed	Пришёл, начат, завершён, не пришёл
patient.created	Новый пациент
patient.updated	Изменилась карточка пациента
payment.created	Оплата или аванс
payment.refunded	Возврат денег
payment.cancelled	Оплата отменена
schedule.changed	Изменилось расписание дня
cash.changed	Движение по кассе
communication.changed	Обращения и заявки
message.changed	Сообщения в чатах
call.updated	Звонок: входящий, разговор, завершён
lab.changed	Заказ в лаборатории: статус, комментарий техника

События записей, пациентов и оплат ставятся в очередь в той же транзакции, что и само изменение. Поэтому событие не теряется, откуда бы ни пришло изменение: из интерфейса, бота, онлайн-записи, API или импорта.

Запрос

POST на ваш адрес с телом:

{"id": "<id доставки>", "event": "appointment.created", "createdAt": "...", "data": {}}

и заголовками:

• X-DentOS-Event — событие;
• X-DentOS-Delivery — id доставки, одинаковый при повторах: по нему удобно отсекать дубли;
• X-DentOS-Signature: t=<unix-время>,v1=<подпись>.

User-Agent запроса — DentOS-Webhooks/1.

Проверка подписи

Подпись — hex(HMAC-SHA256(секрет, "<t>.<сырое тело запроса>")). Пример на Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // старше 5 минут — отбросить
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Проверяй подпись по сырому телу запроса, до разбора JSON.

Повторы

Ответ 2xx — доставлено. Иначе, или если ответа нет 10 секунд, DentOS повторит через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов, 12 часов и сутки. После восьмой попытки доставка помечается неудачной — её можно повторить вручную из журнала доставок.