はじめに
Webhookは、イベントが発生したときにアプリケーション間で情報を交換するための仕組みです。これは、情報を受け取りたいアプリケーション（つまり、受信者）が送信アプリケーションに対してイベントが発生したかどうかを常に問い合わせる必要がないことを意味します。通信は、送信アプリケーションが受信アプリケーションがホストするURLにHTTPリクエストを実行することによって行われ、後者はこのリクエストを処理して特定のアクションを実行できます。
イベントが発生したときに顧客が複数のオプションで情報を受け取れるようにする戦略の一環として、Arcules WebポータルはルールエンジンでWebhookのサポートを含んでいます。この記事では、ルールのためにWebhookを設定する方法と、それがトリガーされたときに受け取ることができる情報について説明します。
設定
1. Arcules Webポータルにアクセスし、その後「ルール」セクションに移動してください：
2. 右上隅にある「+」を押して新しいルールを作成します：
3. ルールの具体的な詳細を設定します。アクションセクションに到達したら、「アクションタイプを選択」オプションで「Webhookを呼び出す」を選択し、対応する入力フィールドに記入してください。
注：APIキーと秘密入力フィールドはオプションです。
ルールアクションとパラメーター
名称 | 説明 | 要件 |
URL | WebhookエンドポイントのURLはHTTPSである必要があります。現時点ではこれは強制されていませんが、将来的に必須となる予定です。 | 必須 |
APIキー | 受信側のWebhookサービスで認証/承認に使用されるAPIキーです。このAPIキーは、リクエスト内で "Authorization" ヘッダーとしてBearerトークンとして含まれます。 | オプショナル |
秘密 | メッセージ署名の生成および検証のためのオプションの共有秘密情報です。設定された場合、リクエストに追加の "X-Arcules-Signature" HTTP ヘッダーが含まれます。メッセージの署名は、受信側のWebhookサービスで検証できます。詳細については以下をご覧ください。 | オプショナル |
通信の詳細
WebhookはPOSTリクエストとして設定されたエンドポイントに送信されます。現在サポートされている認証スキームは、「Authorization」ヘッダーでBearerトークンとして渡されるAPIキーのみです。
Webhookの受信者はできるだけ迅速に応答し、イベントの受信に成功したことを示すために2xxのレスポンスコードで返信することが期待されます。
メッセージ配信は、タイムアウト（408: リクエストタイムアウト & 504: ゲートウェイタイムアウト）の場合、リトライ間に5秒の遅延を含めて最大5回まで試みられます。
注：リダイレクトはサポートされていません。
リクエストヘッダー
以下のHTTPヘッダーが重要です：
名称 | 値 | 注釈 |
Authorization | Bearer API キー | APIKEYは、ルール設定でWebhookを設定する際に入力されるキーです。 注：キーがルールアクションAPIキー（オプショナル）入力フィールドに含まれていない場合、このヘッダーは表示されません。 |
Content-Type | application/json; charset=utf-8 | メッセージの内容はJSON形式のデータです。 |
X-Arcules-Signature | HMAC SHA256 | ルール上のWebhook設定でシークレットが入力されている場合に含まれます。これはメッセージの起源を検証するために使用できるメッセージ署名です。 |
署名の検証
ハッシュ用のシークレットが提供されている場合、X-Arcules-Signatureヘッダーにメッセージ署名が提供されます。受信Webhookサービスで同じシークレットを使用することで、メッセージがArculesサービスによって送信されたことを検証できます。
メッセージ本文
Webhooksメッセージには以下のフィールドが含まれます：
属性 | 種類 | 説明 |
webhook_id | String (UUID) | WebhookメッセージのUUID。メッセージが複数回受信された場合に重複を検出するのに役立ちます。 |
rule_id | String | Webhookが設定されたルールのUUID |
rule_name | String | Webhookが設定されたルールの名前 |
device_id | String | デバイスのUUID |
device_name | String | デバイスの名前 |
device_type | String | トリガーとなるデバイスの識別子 |
event_type | String | センサー/値のタイプ |
region_name | String | 物体検出された領域に指定された名前 |
event_value | デバイスタイプに依存します | イベントに関連する特定の値 |
event_time | String | イベントのタイムスタンプ、RFC 3339に従う形式 |
例
以下は、メッセージ本文の一例です
ユーザー定義デバイス
{
"webhook_id": "f8a8097e-ea52-4b3d-8bbe-191332a478ee",
"rule_id": "2f6144fb-83f3-4d65-bcf3-99a83e219559",
"rule_name": "Rule for Notification on User Defined Device",
"device_id": "6c5b58a5-279b-496e-85c9-60b01d1f5666",
"device_name": "earthquake sensor",
"device_type": "userdefineddevice",
"event_type": "sensoralarm",
"event_value": "alarm",
"event_time": "2024-02-20T23:28:31Z"
}
領域内の車両
{
"webhook_id": "54b57b48-6a5f-43d4-bf80-88f89c53b8db",
"rule_id": "7815f13a-a60c-457d-93a6-6bd22220d163",
"rule_name": "Video Analytics Test",
"device_id": "9917a303-d405-4afe-8cb8-b7dc59c4151b",
"device_name": "Device 1",
"device_type": "video",
"event_type": "vehicleinregion",
"region_name": "Detection Zone 1"
"event_value": 1,
"event_time": "2024-02-20T21:05:09Z"
}
ぶれ検知
{
"webhook_id": "59dcf038-1c35-47d0-9ee6-d57152892342",
"rule_id": "3e2af5d9-66c1-4224-8510-f539423220c6",
"rule_name": "Blur Test 1",
"device_id": "8ced3345-6b06-4f9b-93f4-8f1c7fb8bbe4",
"device_name": "Blur and Rotate",
"device_type": "video",
"event_type": "blurdetection",
"event_value": true,
"event_time": "2024-02-20T23:28:31Z"
}
イベントオプション
デバイスタイプ、イベントタイプ、および値には以下の組み合わせが含まれます（一部の組み合わせは利用できない場合があり、システムの設定によっては他の組み合わせが発生する場合があります）：
デバイス タイプ | イベント タイプ | イベント 値 |
ゲートウェイ | 状態ステータス | オンライン/オフライン |
カメラ 分析 | センサーアラーム | アラーム/通常 |
| カウンター | Integer/Number |
| 人数カウンター | Integer/Number |
ビデオ | 状態ステータス | オンライン/オフライン |
| 地域内の人 | Integer/Number |
| 地域内の車両 | Integer/Number |
| 煙検知 | Boolean |
| Rotation Detection | Boolean |
| 動体検知 | Boolean |
| Tampering Detection | Boolean |
| Blur Detection | Boolean |
| 混雑状況 | Boolean |
| People Loitering | Boolean |
ユーザー定義デバイス | センサーアラーム | アラーム/通常 |
HALO | 状態ステータス | オンライン/オフライン |
| センサーアラーム | アラーム/通常 |
入力/出力 | 状態ステータス | オンライン/オフライン |
| デジタル出力 | Active/Inactive |
| デジタル入力 | Active/Inactive |