Webhooks и polling: как данные биометрии в реальном времени должны попадать на ваш сервер
Любая интеграция биометрии должна ответить на один базовый вопрос: как отметка на входе становится записью в вашей системе? Есть два способа. Ваш сервер может постоянно спрашивать устройство, не произошло ли что-то новое, это polling (опрос). Либо система может сообщить вашему серверу в тот момент, когда что-то произошло, это вебхук (webhook). Для данных посещаемости и контроля доступа выбор между вебхуками и опросом влияет на то, насколько актуальны ваши данные, какую нагрузку создаются на устройства и сети, и насколько надежны ваши записи. В этом руководстве оба подхода объясняются простым языком, показано, почему вебхуки лучше подходят по умолчанию для данных биометрии, описано, как построить надежный приемник вебхуков, и рассказано, где опрос по-прежнему уместен.
01 · Pull vs Push
Два способа передачи данных
Представьте, что вы ждете важную посылку. Можно каждые пять минут выходить к входной двери, чтобы проверить, не пришла ли она. Или можно дождаться звонка в дверь. В обоих случаях вы получите посылку. Но в первом варианте вы тратите много поездок и все равно можете опоздать на пять минут. Во втором вы узнаете о доставке в тот момент, когда она пришла.
Именно это и есть разница между polling и вебхуками.
Polling: ваш сервер постоянно спрашивает
|
Ваш сервер Спрашивает: есть ли новые отметки с прошлого раза? |
→ |
Устройство или система Отвечает: ничего нового |
→ |
Ожидание Пауза на интервал опроса |
→ |
Повтор Спрашивать снова и снова весь день |
Вебхук: система сообщает вашему серверу
|
Отметка сотрудника Подтвержденный отпечаток, лицо или карта |
→ |
Gateway Немедленно отправляет событие на ваш URL вебхука |
→ |
Ваш сервер Получает событие и отвечает «готово» |
→ |
Готово Без ожидания и без лишних запросов |
| Polling | Вебхуки | |
|---|---|---|
| Кто начинает диалог | Ваш сервер | Система, у которой есть данные |
| Когда поступают данные | При следующем опросе, с задержкой до одного полного интервала | Сразу после отметки |
| Запросы, когда ничего не происходит | Постоянные, большинство пустые | Нет |
| Нагрузка на устройства и сеть | Постоянная, вне зависимости от активности | Только когда есть что передать |
| Сложность для вас | Отслеживание уже полученных данных | Прием и подтверждение событий |
02 · The Hidden Costs
Почему polling плохо работает с данными биометрии
Polling подходит для данных, которые меняются медленно или где задержка не важна. Данные посещаемости и контроля доступа по биометрии устроены противоположным образом. Они формируются короткими всплесками в начале и конце смены, в остальное время почти не меняются, и часто нужны немедленно.
Задержка заложена в самой схеме
При polling максимальная задержка всегда равна интервалу опроса. Отметка, которая произошла через секунду после опроса, ждет весь интервал, прежде чем ваш сервер ее увидит.
| Интервал опроса | Максимальная задержка до того, как система узнает | Подходит для |
|---|---|---|
| Раз в 24 часа | До целого дня | Только ежемесячный расчет зарплаты |
| Раз в час | До 60 минут | Ежедневные отчеты |
| Каждые 5 минут | До 5 минут | Большинство дашбордов, но не оповещений |
| Каждую минуту | До 60 секунд | Почти реальное время, но при большом количестве запросов |
| Вебхук | Задержки опроса нет | Дашборды в реальном времени, уведомления и автоматизация |
Большинство запросов впустую
Чтобы приблизиться к реальному времени, вы опрашиваете чаще. Но большинство таких запросов ничего не возвращают. Опрос одного устройства каждую минуту означает 1 440 запросов на устройство в сутки. При 50 устройствах это 72 000 запросов в сутки, и большинство из них задают вопрос, ответ на который: «ничего нового». Каждый такой запрос использует пропускную способность сети и время обработки на устройстве.
Отслеживать становится непросто
Интеграция на основе polling должна помнить, что уже было получено, обычно сохраняя время или позицию последней просмотренной записи. Если этот маркер неверен из-за перезапуска, разницы часов между сервером и устройством или записей, сохраненных во время отсутствия связи с устройством, интеграция либо пропускает отметки, либо импортирует их дважды. Такие проблемы незаметны и часто проявляются только во время спора по зарплате.
С каждым объектом становится сложнее
С одним устройством polling управляем. Но когда есть десятки устройств на нескольких объектах и разных марках, у каждого из которых свое подключение, свой интервал и свой маркер последнего получения, polling превращается в отдельную задачу по планированию и мониторингу.
|
Polling задает один и тот же вопрос тысячи раз в день, чтобы поймать несколько важных моментов. Вебхуки подают сигнал только тогда, когда что-то действительно произошло. |
03 · Push Delivery With Cams
Как работают биометрические вебхуки
В Cams Biometrics Gateway доставка через вебхуки называется Callback API. Вы указываете Gateway URL на вашем сервере, и каждая подтвержденная отметка отправляется на этот URL в момент ее появления. События Callback доставляются без задержки для устройств с Native Push.
Что получает ваш сервер
|
Callback API, запрос, отправленный Gateway на ваш URL вебхука {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
| Поле | Что сообщает вашему серверу |
|---|---|
| OperationID | Уникальный идентификатор этого события |
| LabelName | Название объекта или двери, к которой привязано устройство |
| SerialNumber | Конкретное устройство, которое зафиксировало отметку |
| Type | Отметка прихода или ухода |
| InputType | Как человек прошел подтверждение: отпечаток, лицо, карта, PIN-код и т. д. |
| UserId | Кто сделал отметку, соответствует ID в вашей HR-системе |
| LogTime | Когда произошла отметка на устройстве, со смещением часового пояса |
| AuthToken | Токен, с помощью которого ваш сервер подтверждает подлинность запроса |
| Time | Временная метка самого сообщения, в GMT |
Что ваш сервер должен отправить в ответ
Получив событие, ваш сервер отправляет короткое подтверждение. Это сообщает Gateway, что событие благополучно получено.
|
Callback API, ответ, который должен вернуть ваш вебхук { "status": "done" }
|
|
Push, даже когда устройство не может сам Не каждое устройство может самостоятельно передавать данные. Некоторые старые или непроверенные устройства только сохраняют данные посещаемости в локальной базе данных или файле. С Cams Hybrid Push Gateway может читать эту базу данных (DB Pull) или отслеживать этот файл (File Processing) и по-прежнему доставлять новые записи посещаемости на ваш Callback URL. Ваш сервер получает доставку по схеме push в любом случае, даже если базовое устройство обычно требует опроса. |
04 · Best Practices
Построение надежного приемника вебхуков
Приемник вебхуков несложно построить, но несколько практик определяют разницу между решением, которое работает в тестах, и решением, которое работает каждый день в течение многих лет.
| Практика | Что делать | Почему это важно |
|---|---|---|
| Сначала подтвердить | Отправить статус done сразу после получения события, а более медленную работу выполнять потом | Запрос Gateway остается коротким, даже если ваши последующие системы работают медленно |
| Ставить работу в очередь | Помещать каждое полученное событие в очередь или таблицу и обрабатывать отдельно | Справляется со всплесками в начале смены без потери событий |
| Проверять AuthToken | Проверять токен в каждом запросе перед тем, как доверять данным | Не позволяет никому отправлять поддельные данные посещаемости на ваш URL |
| Использовать HTTPS | Открывать ваш вебхук только по HTTPS, с опциональным шифрованием AES-256 со стороны Gateway | Данные посещаемости являются персональными данными и должны защищаться при передаче |
| Сделать обработку идемпотентной | Использовать OperationID, чтобы обнаруживать и игнорировать уже обработанные события | Повторная доставка никогда не превращается в дубликат записи посещаемости |
| Опираться на LogTime для посещаемости | Учитывать посещаемость по LogTime, а не по времени получения события вашим сервером | События, сохраненные во время сбоя, поступают позже, но сохраняют реальное время отметки |
| Сортировать по LogTime | Упорядочивать события по LogTime перед расчетом часов | Буферизованные события могут прийти не по порядку после обрыва соединения |
| Вести журнал всего | Сохранять запись о каждом полученном событии и каждом отправленном ответе | Упрощает поиск неисправностей и аудит |
|
Планируйте под пики, а не под средние значения На объекте с 300 сотрудниками большую часть дня может не поступать почти ничего, а затем при смене за десять минут приходят 300 событий. Проектируйте приемник под этот пик. Самый простой способ справиться с ним: быстро подтверждать получение и ставить работу в очередь. |
Где может находиться вебхук
Вашему вебхуку нужен публичный HTTPS-адрес, до которого может дотянуться Gateway. Это может быть конечная точка в вашем приложении, небольшая облачная функция или входящий вебхук в инструменте автоматизации, таком как n8n или Make. Сами устройства не требуют публичного IP-адреса. Объекты за межсетевыми экранами могут подключаться к Gateway через Hybrid Connector, который работает через исходящее соединение.
|
Дальнейшие действия определяет ваша система Gateway доставляет подтвержденные события и ждет ваше подтверждение. Что происходит дальше, например запись в вашу HRMS, обновление дашборда, отправка уведомления об опоздании или запуск рабочего процесса, определяют ваше собственное программное обеспечение и правила. |
05 · Using Both Together
Где по-прежнему уместен polling
Вебхуки должны быть вариантом по умолчанию для данных биометрии в реальном времени. Но получение данных по запросу все еще выполняет полезные и конкретные задачи. Наиболее надежные интеграции используют вебхуки для доставки в реальном времени и периодическое получение данных по запросу для проверки и восстановления.
| Ситуация | Лучший подход | Почему |
|---|---|---|
| Посещаемость в реальном времени, дашборды, уведомления | Вебхуки (Callback API) | Данные поступают в момент отметки |
| Ваш сервер был недоступен некоторое время | Получить журналы по запросу | Заполнить любой пробел и убедиться, что ничего не пропущено |
| Ночная или еженедельная сверка | Получать журналы по расписанию | Сравнение с данными, доставленными вебхуками, как страховка |
| Настройка новой интеграции | Однократно получить исторические журналы | Импортировать существующую историю до того, как вебхуки начнут работать |
| Аудит конкретного периода | Получить журналы за этот период | Получить полную запись для проверки |
Для этих задач Cams RESTful API включает операции загрузки журналов с устройств. Используемое периодически и намеренно, получение журналов дополняет вебхуки, а не конкурирует с ними. Разница в намерении: вы запрашиваете данные, когда есть причина, а не спрашиваете каждую минуту на всякий случай.
Часто задаваемые вопросы
|
Бывает ли polling лучше вебхуков для данных биометрии? Polling может быть проще, если ваша система не может открыть никакой публичной конечной точки, или для разовых исторических импортов. Для постоянных данных посещаемости и контроля доступа вебхуки быстрее, создают меньшую нагрузку на устройства и сети и легче масштабируются на несколько объектов. |
|
Что происходит с отметками, если мой сервер вебхуков недоступен? Если ваш сервер вебхуков недоступен, данные посещаемости сохраняются в очереди Cams. Как только ваш сервер снова заработает, записи из очереди автоматически передаются на ваш сервер. Очередь автоматически перезапускается раз в 3 часа, а также вы можете вручную перезапустить ее в любое время из Cams Portal. Это гарантирует, что записи посещаемости не будут потеряны из-за временной недоступности сервера. |
|
Нужен ли моим биометрическим устройствам публичный IP-адрес для работы вебхуков? Нет. Ваш URL вебхука должен быть доступен для Gateway, а устройства не обязаны. Объекты без публичного IP-адреса могут подключаться через Hybrid Connector, который использует исходящее соединение. |
|
Можно ли принимать вебхуки в n8n, Make или Zapier? Да. Любой инструмент, который может принимать входящий вебхук, может получать события Cams Callback. n8n и Make также могут напрямую вернуть требуемое подтверждение done. Zapier может потребовать небольшой релей перед собой, чтобы отправлять этот ответ. |
|
Почему LogTime и Time различаются в передаваемых данных? LogTime — это момент, когда человек действительно сделал отметку, записанный со смещением часового пояса устройства. Time — это временная метка самого сообщения, в GMT. Если устройство было офлайн, сообщение может быть отправлено значительно позже отметки. Для учета посещаемости всегда используйте LogTime. |
Заключение: пусть звонит звонок
Polling имел смысл, когда биометрические устройства можно было читать только по запросу, и никто не ожидал, что данные посещаемости будут поступать в реальном времени. Сегодня HR-дашборды, системы расчета зарплаты, инструменты автоматизации и ИИ-ассистенты лучше всего работают с данными в момент их появления. Задавать устройству один и тот же вопрос тысячи раз в день — медленный и расточительный способ добиться этого.
Вебхуки превращают каждую подтвержденную отметку в событие, которое ваши системы получают сразу, без лишних запросов и без хрупкого отслеживания уже полученных данных. Оставьте получение журналов по запросу для того, в чем оно сильнее всего: заполнение пробелов и проверка полноты, а все остальное передавайте через вебхуки.
Cams Biometrics Gateway построен вокруг доставки по схеме push. Его Callback API отправляет каждую подтвержденную отметку на ваш вебхук в реальном времени с устройств более чем 15 брендов, в едином формате JSON. Режимы Hybrid Push доставляют события push даже с устройств, которые не могут передавать данные самостоятельно, а RESTful API предоставляет операции по запросу, например загрузку журналов для сверки. Вся связь осуществляется по HTTP/HTTPS с проверкой токена авторизации и опциональным шифрованием AES-256. Узнать больше о платформе можно на CamsBiometrics.com, а полную документацию по Callback API — на developer.camsbiometrics.com.