dejirenでのWebhook のご利用について
このページでは、dejiren VA を webhook から起動する方法と、利活用のケースについて説明します。
Webhook について
Webhook (ウェブフック) は、特定のイベントが発生した際に、事前に設定された URL に HTTP リクエストを送信する仕組みです。
これにより、dejiren に専用コネクタが用意されていないサービスともリアルタイムな情報のやり取りが可能になります。
Webhook には
■リアルタイム性 ： イベント発生で即通知を送信できるため、情報伝達の遅延を防ぐことができる
■自動化 ： 手動でのデータチェックや更新が不要になり、業務プロセスの効率化が図れる
■通信コスト削減 ： ポーリングを必要としないため、サーバーへの負荷が軽減される
■柔軟性 ： 送信するデータの形式に制約がなく、多様なシステムと統合可能
といった特徴があります。
dejiren では VA が動くきっかけに [Webhookを受け取ったとき] を指定することができるので、 外部サービスが提供する様々なデータを受信して、処理の自動化や様々なシステムへの連携が図れます。
Webhook の HTTP リクエストメソッド
WebhookのHTTPリクエストメソッドには POST と GET があります。
通常は POST を指定することがほとんどですが、用途に応じて適切なものをご選択ください。
| HTTP リクエストメソッド | 用途 |
|---|---|
| POST | イベントが発生した際にデータを送信するために使用。 送信側が受信側にデータをプッシュという形態の動作です。 リアルタイムで情報を提供するのに適しています。 |
| GET | データを取得するために使用。 Webhookではあまり一般的ではなく、特定のAPIエンドポイントからデータをfetchする際に用いられます。 |
WebhookのPOSTメソッドで取得できる情報の例
| 情報種別 | 具体的な情報 |
|---|---|
| イベントタイプ | どのようなイベントが発生したか（例：メッセージ送信、ユーザー登録）を取得します。 |
| タイムスタンプ | イベントが発生した日時を取得します。 |
| ユーザー情報 | イベントを引き起こしたユーザーの ID や名前を取得します。 |
| コンテンツ | メッセージやファイルなどの具体的な内容を取得します。 |
| 追加情報 | イベントに関連するメタデータやカスタムパラメータを取得します。 |
WebhookのGETメソッドで取得できる情報の例
| 情報種別 | 具体的な情報 |
|---|---|
| メッセージコンテンツ | メッセージ ID を使って画像や動画などのメディアファイルを取得します。 |
| ユーザープロフィール | ユーザー ID を使ってプロフィール情報（表示名、プロフィール画像など）を取得します。 |
| イベント詳細 | イベント ID を指定して、そのイベントに関する詳細情報を取得できます。 |
前提条件・必要な権限
lWebhook の利用設定を行う際に必要な権限は下記のとおりです。
| サービス | 必要な権限 |
|---|---|
| dejiren | VA 編集者、もしくは VA 管理者権限ロールに属するアカウント。 |
| 連携先サービス | webhook の設定項目があり、設定可能であること。 ※必要な権限は各サービスの公式情報をご確認ください。 |
※ [動作のきっかけ]に[Webhook]を選択した場合の VA 手順書作成に必要な権限のみ記しています。
手順書の設定内容により、ほかに権限が必要な場合があります。
設定手順
1.dejiren の VA 管理画面にアクセスします。
https://www.dejiren.com/va
2.[VA]画面で、画面左上の[新規作成]をクリックします。
3.[新規作成]で、入力が必須の各項目を入力・選択して、[アクセス権を設定する]をクリックします。
| 設定項目 | 設定値 | 入力要否 |
| 名前 | このVAを識別するための任意の名称 | 必須 |
| 自己紹介 | このVAの説明 | 任意 |
| ラベル | このVAに付与するタグ | 任意 |
| 利用対象 | [わたしのVA]・[みんなのVA] | いずれかを指定 |
| VAが動くきっかけ | Webhookを受け取ったとき | 必須 |
4.VA の利用権限を設定します。
5.手順書編集画面が表示されるので、きっかけに配置された
[Webhookを受け取ったとき] ブロックをクリックして開きます。
6.[webhookを発行する]の下に、初期状態で webhook URL が表示されているので、
Webhook URL の右にあるコピーボタンをクリックして文字列を控えます。
7.連携先サービスと適応するように、各項目の設定を行います。
[追加]をクリックして必要な分パラメーターを登録します。
各項の入力が完了したら[追加]をクリックしてパラメーターを登録します。
8.[決定する]をクリックしてwebhook設定を閉じます。
9.[手順書編集]画面に、任意の手順ブロックを配置して設定します。
たとえば、[値で分岐]ブロックを配置して、
受信したパラメーターキーの値により処理を分岐させ、
ある値に一致したときには[チャット送信]、
不一致のときには[dejirenデータベース]の[レコード登録]を配置、
などとします。
10.手順書編集が完了したら、画面上部の[保存]をクリックして手順書を保存します。
11.連携先サービスで、dejiren で発行したwebhook (手順⑥) 、
securityKey やパラメーターキー (手順⑦) を設定します。
※securityKeyのKは大文字です。
・連携先により、設定に必要な権限が異なります。
・連携先の設定方法は各公式情報をご確認ください。
12.VA 管理画面の手順書編集画面上部の[停止中]と表示されている箇所をクリックして、
VA の動作状態を[稼働中]に変更します。
13.これ以降、連携先のサービスでイベントが発生したときなどで、
dejiren に Webhook が連携されます。
連携先で任意のイベントを発生させ、動作の検証・試験を行い、
必要に応じて手順⑥のパラメーターの設定を見直してください。
補足説明
- 受信するJSON文字列のパラメーターキーは、
A..a、A..a..aa といったように、
ピリオドでつなぎます。 …① - 配列形式の場合は [0].Aのように配列の順番を記載します。 …②
- 受信したパラメーターキーを、
テキスト切り出しブロックとテキスト分割ブロックを利用して
配列（リスト）にして利用できます。…③④
webhook の動作試験
PC のターミナルコンソールで、試験として dejiren の webhook をキックするには下記のコマンドを用います。
| Windows | curl –header “Content-Type: application/json” -d “{\”パラメーター1の名称\”:\”パラメーター1の値\”,\”パラメーター2の名称\”:\”パラメーター2の値\”}” https://～dejirenのWebhookURL |
| macOS | curl –json ‘{“パラメーター1の名称”:”パラメーター1の値”,”パラメーター2の名称”:”パラメーター2の値”,”パラメーター3の名称”:”パラメーター3の値”}’ \ https://～dejirenのWebhookURL |
セキュリティキーを含めて webhook をキックする場合には下記のようなコマンドを用います。
| Windows | curl –header “Content-Type: application/json” -d “{\”パラメーター1の名称\”:\”パラメーター1の値\”,\”パラメーター2の名称\”:\”パラメーター2の値\”}” https://～dejirenのWebhookURL/?securityKey=セキュリティキー” |
| macOS | curl –json ‘{“パラメーター1の名称”:”パラメーター1の値”,”パラメーター2の名称”:”パラメーター2の値”,”パラメーター3の名称”:”パラメーター3の値”}’ “https://～dejirenのWebhookURL/?securitykey=セキュリティキー” |
・URLの末尾に/?securityKey=セキュリティキーの値を追加します。
※Kは大文字です。 URL全体をダブルクォート “” で囲みます。
・セキュリティキーは、Webhook が適切なリクエストかどうか判断するために使用します。
・セキュリティキーは初期状態では未設定（空白）ですが、
値を手動入力、もしくは[自動生成]をクリックして自動生成した時点で、
セキュリティキーは必須パラメーターになります。
・securityKeyはクエリストリング、ボディ(JSON)内どちらでも機能します。
(上記はクエリストリングのケース例です。)
JSON ファイル (この例では”data.json”) を用いて curl を使用する場合には下記のようなコマンドを用います。
| Windows | curl -H “Content-Type: application/json” -d @data.json “https://～dejirenのWebhookURL/?securityKey=セキュリティキー” |
| macOS | curl -X POST \ -H “Content-Type: application/json” \ -d @data.json \ ” https://～dejirenのWebhookURL/?securityKey=セキュリティキー” |
data.json の内容は下記のように記載します。
{“parameter1″:”value1″,”parameter2″:”value2”}
★テスト用 cURL を Bat ファイルにする場合には、UTF-8 (BOM付) でファイル保存します。
(bat の冒頭で chcp で文字コードを 65001 に指定しても正常に処理されない場合があります。)
・bat 内に複数のパラメータを記載した場合、一部のパラメータが取得できない場合があります。
その場合には、先行の手法に倣って bat ファイルと同じ領域に json ファイルを保存して参照するようにします。
#webhook #ウェブフック #JSON #ジェイソン #httpアクセス #httpリクエスト #httpsアクセス #httpsリクエスト #汎用
