#Webhook

This feature is provided by the commercial plugin «ワークフロー：Webhook トリガー», please purchase to use

#概要

Webhookトリガーは、外部システムからHTTPリクエストで呼び出せるURLを提供します。外部イベント発生時にそのURLへHTTPリクエストを送信し、ワークフローの実行をトリガーします。支払い通知やメッセージなど、外部システムからの通知に利用できます。

#ワークフローの作成

ワークフローを作成する際、タイプで「Webhook イベント」を選択します。

#トリガー設定

#Webhook URL

WebhookトリガーのURLはシステムによって自動生成され、このワークフローに紐付けられます。右側のボタンをクリックしてコピーし、外部システムに貼り付けてください。

HTTPメソッドはPOSTのみサポートしており、他のメソッドでは405エラーが返されます。

#セキュリティ

現在、HTTPベーシック認証をサポートしています。このオプションを有効にしてユーザー名とパスワードを設定することで、外部システムのWebhook URLにユーザー名とパスワードを含め、Webhookのセキュリティ認証を実現できます（標準の詳細については、MDN: HTTP authenticationを参照してください）。

ユーザー名とパスワードが設定されている場合、システムはリクエスト内のユーザー名とパスワードが一致するか検証します。提供されていない場合や一致しない場合は、401エラーが返されます。

#リクエストデータの解析

外部システムがWebhookを呼び出す際、リクエストに含まれるデータは、ワークフローで使用する前に解析する必要があります。解析されたデータはトリガー変数として、後続のノードで参照できるようになります。

HTTPリクエストの解析は3つの部分に分かれます。

1. リクエストヘッダー

   リクエストヘッダーは通常、シンプルな文字列型のキーと値のペアです。使用したいリクエストヘッダーフィールドは、DateやX-Request-Idなどのように直接設定できます。

2. リクエストパラメータ

   リクエストパラメータはURLのクエリパラメータ部分です。例えば、http://localhost:13000/api/webhook:trigger/1hfmkioou0d?query=1におけるqueryパラメータなどが該当します。完全なURLのサンプル、またはクエリパラメータ部分のみのサンプルを貼り付け、「解析」ボタンをクリックすると、キーと値のペアが自動的に解析されます。

   

   自動解析により、URLのパラメータ部分はJSON構造に変換され、パラメータの階層に基づいてquery[0]、query[0].aなどのパスが生成されます。このパス名は、必要に応じて手動で変更できますが、通常は変更不要です。エイリアスは変数として使用する際の表示名で、オプションです。また、解析によりサンプルに含まれるすべてのパラメータのリストが生成されます。不要なパラメータがあれば削除できます。

3. リクエストボディ

   リクエストボディはHTTPリクエストのBody部分です。現在、Content-Typeがapplication/json形式のリクエストボディのみをサポートしています。解析したいパスを直接設定することも、JSONサンプルを入力して「解析」ボタンをクリックし、自動解析することもできます。

   

   自動解析により、JSON構造内のキーと値のペアがパスに変換されます。例えば、{"a": 1, "b": {"c": 2}}からはa、b、b.cなどのパスが生成されます。エイリアスは変数として使用する際の表示名で、オプションです。また、解析によりサンプルに含まれるすべてのパラメータのリストが生成されます。不要なパラメータがあれば削除できます。

#レスポンス設定

Webhookのレスポンス部分は、同期ワークフローと非同期ワークフローで設定方法が異なります。非同期ワークフローでは、レスポンスはトリガー内で直接設定します。Webhookリクエストを受信すると、トリガーで設定されたレスポンスをすぐに外部システムに返し、その後ワークフローを実行します。一方、同期ワークフローでは、ビジネス要件に応じてフロー内にレスポンスノードを追加して処理する必要があります（詳細はレスポンスノードを参照してください）。

通常、非同期でトリガーされるWebhookイベントのレスポンスは、ステータスコードが200、レスポンスボディがokです。状況に応じて、レスポンスのステータスコード、ヘッダー、ボディをカスタマイズすることも可能です。

#レスポンスノード

参照：レスポンスノード

#例

Webhookワークフローでは、ビジネス条件に応じて異なるレスポンスを返すことができます。以下の図をご覧ください。

条件分岐ノードを使用して、特定のビジネス状態が満たされているかを判断し、満たされていれば成功を返し、そうでなければ失敗を返します。