Вебхуки
Получайте HTTP-запросы в момент создания, подтверждения, переноса, отмены или завершения записи для интеграции BookifyLabs с вашими системами.
Добавление конечной точки (endpoint)
- Войдите под аккаунтом владельца, откройте Настройки на уровне компании и найдите карточку Вебхуки.
- Нажмите Добавить конечную точку и введите публичный URL-адрес с https://. Локальные адреса (localhost) и частные сети не поддерживаются.
- Скопируйте секрет подписи (signing secret), который отобразится после создания. Он начинается с
whsec_и показывается только один раз. - Отправьте тестовое событие, создав запись, затем проверьте список Доставки.
Вы можете добавить до 5 конечных точек на компанию. Каждую точку можно приостанавливать, возобновлять, менять URL, перегенерировать секрет или удалять вместе с историей доставок.
События
| Событие | Когда отправляется |
|---|---|
appointment.created | Создана запись (онлайн, через Booky или сотрудником). |
appointment.confirmed | Ожидающая запись подтверждена. |
appointment.rescheduled | Изменены время записи или специалист. |
appointment.cancelled | Запись отменена вами или клиентом. |
appointment.completed | Запись отмечена как завершенная через экран завершения. |
Формат запроса
Каждая доставка представляет собой POST-запрос с JSON-телом. Объект data содержит снимок записи на момент наступления события; повторные попытки отправляют то же самое тело.
POST https://example.com/hooks/bookify
Content-Type: application/json
User-Agent: BookifyLabs-Webhooks/1.0 (+https://bookifylabs.com)
X-Bookify-Event-ID: evt_3f6c…
X-Bookify-Timestamp: 1757145600
X-Bookify-Signature: 4b1d…
{
"id": "evt_3f6c…",
"type": "appointment.created",
"created_at": 1757145600,
"data": {
"appointment": { "id": 1234, "status": "booked", "start_at": "…", "…": "…" }
}
}Проверка подписи
Подпись представляет собой 16-ричный хэш HMAC-SHA256 от строки <timestamp>.<raw body>, сформированный с использованием вашего секрета. Рассчитывайте ее из необработанного (raw) тела запроса до парсинга JSON и сравнивайте с помощью функции с постоянным временем выполнения (constant-time).
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-bookify-timestamp"];
const sig = headers["x-bookify-signature"];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // старше 5 минут
const expected = crypto
.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}- Отклоняйте метки времени (timestamps) старше 5 минут для защиты от повторных атак.
- Устраняйте дубликаты по заголовку X-Bookify-Event-ID: повторные попытки содержат тот же ID.
- Отвечайте любым кодом 2xx в течение 10 секунд. Длительные операции выполняйте асинхронно после ответа.
Повторные попытки и история доставок
Запрос, завершившийся по таймауту или получивший ответ 408, 425, 429 или любой 5xx, повторяется каждые 12 часов (до 30 попыток). Перенаправления не поддерживаются, а другие ответы 4xx считаются окончательной ошибкой. В таблице Доставки отображается статус события (ожидает, отправляется, повтор, доставлено, ошибка), количество попыток, сохраненный ответ (до 4 КБ) и время следующей попытки. Недоставленные события можно отправить вручную кнопкой Повторить сейчас. История хранится 30 дней.