Support Hub/API & Integrations/Webhookとポーリングの比較:リアルタイムの生体認証データをサーバーに届ける方法
Translated from the English article and reviewed by a person. Read the English original
Developer

Webhookとポーリングの比較:リアルタイムの生体認証データをサーバーに届ける方法

Webhookとポーリングの比較:リアルタイムの生体認証データをサーバーに届ける方法

すべての生体認証連携では、次の基本的な問いに答える必要があります。ドアでの打刻は、どのようにしてシステム上の記録になるのか。方法は2つあります。サーバーがデバイスに対して新しいイベントがあるかを問い合わせ続けるのがポーリングです。一方、イベントが発生した瞬間にシステムがサーバーへ通知するのがWebhookです。勤怠およびアクセスの生体認証データにおいて、Webhookとポーリングのどちらを選ぶかは、データの鮮度、デバイスやネットワークへの負荷、そして記録の信頼性に影響します。本ガイドでは両方のアプローチをわかりやすく説明し、生体認証データにはWebhookがなぜ適切な既定値なのかを示します。さらに、信頼性の高いWebhook受信部の構築方法を解説し、ポーリングが今もなお役立つ場面についても説明します。

01 · プルとプッシュ

データが届く2つの方法

重要な荷物を待っている場面を想像してください。5分ごとに玄関まで歩いて行き、荷物が届いたかを確認することもできます。あるいは、玄関のチャイムが鳴るのを待つこともできます。どちらでも荷物は受け取れます。前者は何度も無駄な移動をすることになり、それでも最大5分遅れます。後者は荷物が届いた瞬間に知らせてくれます。

これがポーリングとWebhookの違いです。

ポーリング:サーバーが問い合わせ続ける

サーバー

前回以降に新しい打刻はあるか問い合わせる

→

デバイスまたはシステム

新しいものはないと応答する

→

待機

ポーリング間隔の分だけ待つ

→

繰り返し

一日中、何度も問い合わせを続ける

Webhook:システムがサーバーに通知する

従業員の打刻

本人確認済みの指紋、顔、またはカードによる打刻

→

ゲートウェイ

イベントをWebhook URLへ直ちに送信する

→

サーバー

イベントを受信し、完了の応答を返す

→

完了

待機も無駄なリクエストもなし

ポーリング Webhook
やり取りを開始する主体 サーバー データを持つシステム
データが届くタイミング 次回のポーリング時。最大で1間隔分遅れる 打刻の直後
何も起きていないときのリクエスト 継続的に発生し、そのほとんどは空の応答 なし
デバイスとネットワークへの負荷 利用状況にかかわらず常に発生 送信すべきデータがあるときだけ発生
利用者側の複雑さ 取得済みのデータを管理する必要がある イベントを受信し、受信応答を返す必要がある

02 · 見えにくいコスト

生体認証データでポーリングが苦労する理由

ポーリングは、ゆっくり変化するデータや、遅延が問題にならないデータには有効です。しかし、生体認証による勤怠およびアクセスのデータは、その正反対の性質を持っています。始業時と終業時に集中して発生し、それ以外の時間はほとんど動きがなく、しかも多くの場合すぐに必要とされます。

遅延は仕組みに組み込まれている

ポーリングでは、最悪の場合の遅延は必ずポーリング間隔と等しくなります。あるポーリングの1秒後に発生した打刻は、サーバーが認識するまでに間隔全体を待つことになります。

ポーリング間隔 システムが把握するまでの最悪の遅延 十分な用途
24時間ごと 最大で丸1日 月次の給与計算のみ
1時間ごと 最大60分 日次レポート
5分ごと 最大5分 ほとんどのダッシュボード(アラートには不向き)
1分ごと 最大60秒 ほぼリアルタイムだが、リクエストコストが高い
Webhook ポーリングによる遅延なし ライブダッシュボード、通知、自動化

多くのリクエストが無駄になる

リアルタイムに近づけるには、ポーリングの頻度を上げる必要があります。しかし、そのリクエストの多くは何も返しません。1台のデバイスを1分ごとにポーリングすると、1台あたり1日1,440回のリクエストになります。50台では1日72,000回のリクエストとなり、そのほとんどは「新しいものはない」という答えしか返ってこない問い合わせです。こうしたリクエストのひとつひとつが、ネットワークの帯域とデバイスの処理時間を消費します。

データの管理が脆くなる

ポーリングによる連携では、すでに取得したデータを覚えておく必要があり、通常は最後に取得したレコードの時刻や位置を保存します。その目印が、再起動、サーバーとデバイスの時計のずれ、デバイスのオフライン中に保存されたレコードなどが原因で誤っていると、連携は打刻を取りこぼすか、二重に取り込んでしまいます。こうした問題は表面化しにくく、多くの場合は給与計算での食い違いをきっかけに初めて発覚します。

拠点が増えるほど難しくなる

デバイスが1台だけであれば、ポーリングは扱いやすいものです。しかし、複数の拠点やブランドにまたがる数十台のデバイスがあり、それぞれが独自の接続、独自の間隔、独自の最終取得位置を持つ場合、ポーリングはそれ自体がスケジュール管理と監視の仕事になってしまいます。

ポーリングは、重要な瞬間をわずかに捉えるために、同じ問いを1日に何千回も投げかけます。Webhookは、実際に何かが起きたときにだけ通知します。

03 · Camsによるプッシュ配信

生体認証Webhookの仕組み

Cams Biometrics Gatewayでは、Webhook配信はCallback APIと呼ばれます。ゲートウェイにサーバー上のURLを設定すると、本人確認済みのすべての打刻が発生するたびにそのURLへ送信されます。Native Pushに対応するデバイスの場合、Callbackイベントは遅延ゼロで配信されます。

サーバーが受け取るデータ

Callback API、ゲートウェイからWebhook 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と照合できる
LogTime デバイス上で打刻が行われた日時(タイムゾーンのオフセット付き)
AuthToken リクエストが正規のものであることを確認するためにサーバーが使用するトークン
Time メッセージ自体のタイムスタンプ(GMT)

サーバーが返さなければならないもの

サーバーがイベントを受信したら、短い受信確認応答を返します。これにより、ゲートウェイはイベントが無事に届いたことを把握できます。

Callback API、Webhookが返す必要のある応答

{ "status": "done" }

デバイスがプッシュできなくても配信

すべてのデバイスが自らデータをプッシュできるわけではありません。古い機種や未認証のデバイスの中には、勤怠データをローカルのデータベースやファイルに保存するだけのものもあります。Cams Hybrid Pushを使うと、ゲートウェイがそのデータベースから読み取り(DB Pull)、またはそのファイルを監視(File Processing)して、新しい勤怠レコードをCallback URLへ配信できます。基盤のデバイスが本来ポーリングを必要とする場合でも、サーバーはどちらの方法でもプッシュ配信を受け取れます。

04 · ベストプラクティス

信頼性の高いWebhook受信部の構築

Webhook受信部は簡単に作れますが、いくつかの実践的な方法によって、テストでは動くだけのものと、何年にもわたって毎日安定して動くものとの差が生まれます。

実践項目 実施内容 重要な理由
先に受信確認を返す イベントを受信したらすぐにdone状態を返し、時間のかかる処理はその後に行う 後続システムの処理が遅くても、ゲートウェイからのリクエストを短く保てる
処理をキューに入れる 受信したイベントをそれぞれキューまたはテーブルに保存し、個別に処理する 始業時の集中的な打刻を、イベントを取りこぼさずに処理できる
AuthTokenを検証する データを信頼する前に、リクエストごとにトークンを確認する 第三者がURLへ偽の勤怠データを投稿することを防ぐ
HTTPSを使用する WebhookはHTTPSのみで公開し、ゲートウェイからの任意のAES-256暗号化を利用する 勤怠データは個人データであり、通信中も保護しなければならない
冪等性を確保する OperationIDを使って、処理済みのイベントを検出し無視する 同じイベントが再送されても、勤怠記録が重複することはない
勤怠にはLogTimeを使う サーバーがイベントを受信した時刻ではなく、LogTimeを使って勤怠を記録する 障害中に保存されたイベントは後から届くが、本来の打刻時刻を保持している
LogTimeで並べ替える 労働時間を計算する前に、イベントをLogTimeの順に並べる 接続が切れた後、バッファされたイベントは順序が前後して届くことがある
すべてを記録する 受信したすべてのイベントと、送信したすべての応答の記録を残す トラブルシューティングと監査を円滑にする

平均ではなく集中的な負荷を想定する

従業員300名の拠点では、一日の大半はほとんど何も受信しなくても、交代時には10分間で300件のイベントが届くことがあります。受信部はそのピークを前提に設計してください。素早く受信確認を返し、処理をキューに入れることが、最も単純な対処法です。

Webhookの配置先

Webhookには、ゲートウェイから到達可能な公開HTTPSアドレスが必要です。自社アプリケーションのエンドポイント、小規模なクラウド関数、またはn8NやMakeなどの自動化ツールの受信Webhookを使うこともできます。デバイス自体に公開IPは必要ありません。ファイアウォールの内側にある拠点は、Hybrid Connectorを通じてゲートウェイに接続できます。Hybrid Connectorは外向きの接続で動作します。

その後の処理はシステムが決める

ゲートウェイは本人確認済みのイベントを配信し、受信確認を待ちます。その後の処理(HRMSへの書き込み、ダッシュボードの更新、遅刻通知の送信、ワークフローの開始など)は、お客様自身のソフトウェアとルールによって決まります。

05 · 両方を組み合わせて使う

ポーリングが今も役立つ場面

ライブの生体認証データには、Webhookを標準として使うべきです。ただし、要求に応じてデータを取得する方法にも、有用で明確な役割があります。最も強力な連携は、リアルタイム配信にはWebhookを使い、確認や復旧のために必要なときだけオンデマンドで取得するという形です。

状況 最適なアプローチ 理由
ライブの勤怠、ダッシュボード、通知 Webhook(Callback API) 打刻が発生した瞬間にデータが届く
サーバーが一定期間オフラインだった 要求に応じてログを取得 空白期間を埋め、取りこぼしがないことを確認する
夜間または週次の照合 スケジュールに従ってログを取得 Webhookで配信された内容と比較し、安全網とする
新しい連携を設定する 過去のログを一度だけ取得 Webhookが引き継ぐ前に、既存の履歴を取り込む
特定期間の監査 その期間のログを取得 確認用に完全な記録を作成する

これらの用途には、Cams RESTful APIにデバイスからログを読み込む操作が含まれています。ログの取得は、必要なときに意図的に使えば、Webhookと競合するのではなくWebhookを補完します。違いは目的にあります。念のために毎分問い合わせるのではなく、理由があるときに取得するのです。

よくあるご質問

生体認証データにおいて、ポーリングがWebhookより優れている場合はありますか。

システムが公開エンドポイントをまったく公開できない場合や、一度限りの過去データの取り込みの場合は、ポーリングのほうが簡単なことがあります。継続的な勤怠およびアクセスデータについては、Webhookのほうが高速で、デバイスやネットワークへの負荷も小さく、拠点間でも拡張しやすくなります。

Webhookサーバーが停止した場合、打刻データはどうなりますか。

Webhookサーバーが停止している間、勤怠データはCamsのキューに保存されます。サーバーが再びオンラインになると、キューに入ったレコードは自動的にサーバーへ送信されます。キューは3時間ごとに自動的に再起動され、Cams Portalからいつでも手動で再起動することもできます。これにより、一時的なサーバー停止によって勤怠レコードが失われることを防げます。

Webhookを機能させるために、生体認証デバイスに公開IPは必要ですか。

いいえ。WebhookのURLはゲートウェイから到達可能である必要がありますが、デバイスは到達可能である必要はありません。公開IPを持たない拠点は、外向きの接続を使うHybrid Connectorを通じて接続できます。

n8n、Make、Zapierでwebhookを受信できますか。

はい。受信Webhookに対応しているツールであれば、Cams Callbackのイベントを受信できます。n8nとMakeでは、必要なdone応答を直接返すこともできます。Zapierでは、その応答を返すために前段に小さな中継サーバーが必要になる場合があります。

ペイロードでLogTimeとTimeが異なるのはなぜですか。

LogTimeは本人が実際に打刻した日時で、デバイスのタイムゾーンオフセット付きで記録されます。Timeはメッセージ自体のタイムスタンプで、GMTで表されます。デバイスがオフラインだった場合、メッセージは打刻からかなり後に送信されることがあります。勤怠にはつねにLogTimeを使用してください。

結論:チャイムを鳴らしてもらう

生体認証デバイスが要求に応じてのみ読み取れて、勤怠データがリアルタイムであると誰も期待していなかった時代には、ポーリングにも合理性がありました。しかし今日では、人事ダッシュボード、給与計算システム、自動化ツール、AIアシスタントは、データが生成された瞬間に受け取るときに最も効果を発揮します。デバイスに同じ問いを一日に何千回も投げかけるのは、そこに到達するための遅く無駄な方法です。

Webhookは、本人確認済みのすべての打刻を、システムがすぐに受け取れるイベントに変えます。無駄なリクエストもなく、取得済みのデータを脆く管理する必要もありません。オンデマンドのログ取得は、空白を埋めることや完全性を確認することという本来の用途に限定し、それ以外のすべてはWebhookに任せてください。

Cams Biometrics Gatewayは、プッシュ配信を中心に設計されています。そのCallback APIは、15以上のブランドのデバイスから、本人確認済みのすべての打刻を統一されたJSON形式でリアルタイムにWebhookへ送信します。Hybrid Pushモードでは、単独ではプッシュできないデバイスからもプッシュイベントを配信できます。RESTful APIは、照合のためのログ読み込みなど、オンデマンドの操作を提供します。すべての通信はHTTP/HTTPS上で行われ、認証トークンの検証と任意のAES-256暗号化に対応しています。プラットフォームの詳細はCamsBiometrics.comをご覧ください。Callback APIの完全なドキュメントはdeveloper.camsbiometrics.comでお読みいただけます。

Was this article helpful?