События
Вебхук можно подписать на 21 событие:
device.registered,device.online,device.blocked,device.unblocked,device.deletedsession.started,session.endeduser.signup,user.signup_pending,user.signin,user.email_verified,user.password_changed,user.sso_linked,user.sso_unlinkedadmin.policy_changed,group.policy_changedbilling.payment_succeeded,billing.subscription_canceled,billing.subscription_expiringrecording.uploaded,recording.deleted
billing.subscription_expiring приходит за 10, 5 и 1 день до конца платной подписки - по нему интеграция успевает продлить тариф до отключения. recording.deleted нужен, если вы храните у себя ссылки на записи: по нему видно, что объекта в хранилище больше нет. device.deleted приходит, когда устройство снято с учёта в организации: в отличие от временной недоступности (статус «не в сети» виден в кабинете), удалённое устройство исчезает из организации и не вернётся под тем же идентификатором.
Доступно на тарифах Pro и выше.
Заголовки запроса
| Заголовок | Назначение |
|---|---|
X-Webhook-Event | Тип события |
X-Webhook-Signature | Подпись тела запроса, вида sha256=<hex> |
X-Webhook-Timestamp | Время отправки в миллисекундах - нужно для проверки подписи и для отсечения старых повторов |
X-Webhook-Delivery | Идентификатор доставки - используйте его, чтобы не обработать одно и то же событие дважды |
Проверка подписи
Подпись - это HMAC-SHA256 от строки ${timestampMs}.${rawBody}, посчитанный с секретом подписки, где timestampMs - значение заголовка X-Webhook-Timestamp, а rawBody - тело запроса ровно в том виде, в котором оно пришло (до разбора JSON). Соберите ту же строку, посчитайте HMAC с секретом и сравните с X-Webhook-Signature. Сравнивать нужно постоянным по времени сравнением (constant-time compare), а не обычным == - иначе разницу во времени ответа можно использовать, чтобы подобрать подпись.
Отбрасывайте доставки, у которых время в заголовке далеко ушло от текущего: подпись сама по себе не мешает переслать старый запрос повторно.
Повторные попытки и история
Если доставка не удалась, PCDesk повторяет её до пяти раз с растущими паузами: примерно сразу, через 5 секунд, через 25 секунд, через 2 минуты и через 10 минут. Ответ ждём 10 секунд. Если подписка отдаёт ошибки подряд, после десяти неудач она отключается - в кабинете это видно, включать обратно нужно руками. Историю всех попыток - что отправлено, с каким статусом и когда - видно там же.
Смена секрета
Секрет подписи можно перевыпустить в кабинете без остановки интеграции. Новые доставки сразу подписываются новым секретом, но если приёмник их отвергает, в течение десяти минут после смены PCDesk повторит доставку подписью прежнего секрета - этого запаса хватает, чтобы обновить настройку у себя, ничего не потеряв.