はじめに
トリガーは workflow アプリケーションでのみ利用可能です。
-
workflow に Webhook トリガーを追加すると、一意の Webhook URL が生成されます。これは、外部 HTTP リクエストをリッスンする専用エンドポイントです。
セルフホスティング環境では、
TRIGGER_URL環境変数でこのURLのベースプレフィックスを変更できます。プレフィックスは外部システムからアクセス可能な公開ドメインまたはIPアドレスを指定してください。 -
この URL を使用して、外部システムで監視したいイベントをサブスクライブする Webhook を作成します。次に、Webhook トリガーを設定して、受信リクエストの処理方法とリクエストデータの抽出方法を定義します。
テスト目的では、常にテスト Webhook URL を使用して、テストデータを本番データから分離してください。
- サブスクライブしたイベントが発生すると、外部システムはイベントデータを含む HTTP リクエストを提供された Webhook URL に送信します。リクエストが正常に受信および処理されると、workflow がトリガーされ、指定されたイベントデータが変数として抽出され、ダウンストリームノードで参照できるようになります。
Webhook トリガーの追加
workflow キャンバスで右クリックし、ブロックを追加 > 始める > Webhook トリガーを選択します。Webhook トリガーの設定
Webhook トリガーが受信 HTTP リクエストを処理する方法を定義できます。以下が含まれます：- Webhook URL が期待する HTTP メソッド
- リクエストのコンテンツタイプ
- リクエストから抽出したいデータ
- workflow が正常にトリガーされたときに外部システムに返送されるレスポンス
未公開の Webhook トリガーをテストするには、まずこのステップ実行をクリックするか、workflow 全体をテスト実行する必要があります。これによりトリガーがリスニング状態になり、外部リクエストを受信できるようになります。そうしないと、リクエストはキャプチャされません。
HTTP メソッド
受信リクエストが正常に受信されるようにするには、Webhook URL が受け入れる HTTP メソッドを指定する必要があります。 ここで選択するメソッドは、外部システムがリクエストを送信するときに使用するメソッドと一致する必要があります。そうしないと、リクエストは拒否されます。コンテンツタイプ
リクエストボディを適切に解析し、必要なデータを抽出できるようにするには、受信リクエストの期待されるコンテンツタイプを指定する必要があります。 ここで選択するコンテンツタイプは、外部システムから送信されるリクエストのコンテンツタイプと一致する必要があります。そうしないと、リクエストは拒否されます。Query Parameters、Header Parameters、Request Body Parameters
受信リクエストの Query Parameters、Header Parameters、Request Body Parameters から特定のデータを抽出できます。抽出された各パラメータは、workflow で使用できる出力変数になります。 一部の外部システムは、各リクエストの配信ログを提供しており、リクエストに含まれるすべてのデータを表示し、どのパラメータを抽出するかを決定できます。 または、Webhook トリガーにテストリクエストを送信し、最後の実行ログで受信したリクエストデータを確認することもできます：- 提供されたテスト Webhook URL を使用して、外部システムで Webhook を作成します。
- トリガーで正しい HTTP メソッドとコンテンツタイプを設定します。
- このステップ実行アイコンをクリックします。トリガーは外部リクエストのリスニングを開始します。
- 外部システムでサブスクライブしたイベントをトリガーして、提供された Webhook URL に HTTP リクエストを送信します。
- トリガーの最後の実行タブに移動し、入力で受信したリクエストデータを確認します。
トリガーで定義する変数名は、リクエスト内の対応するパラメータのキー名と一致する必要があります。
- Query Parameters
- Header Parameters
- Request Body Parameters
-
外部システムがリクエストを送信する際に Webhook URL（
?の後）に追加するキーと値のペアのパラメータで、各ペアは&で区切られます。 - 通常、イベントに関する単純で機密性のない識別子またはフィルタデータです。
-
例：URL
{webhook url}?userID=u-456&source=emailから、userID（u-456）またはsource（email）を抽出できます。
-
変数名: リクエスト内のパラメータのキー名（例：
userID=u-456のuserID）。Header Parameters の場合、変数名内のハイフン（-）は、出力変数でアンダースコア（_）に自動的に変換されます。 - タイプ：期待されるデータ形式。Query Parameters と Request Body Parameters にのみ使用できます。Header Parameters は常に文字列として扱われます。
- 必須：workflow が適切に実行されるためにパラメータが必要かどうか。受信リクエストに必須パラメータが欠落している場合、workflow はトリガーされません。
レスポンス
ワークフローが外部HTTPリクエストによって正常にトリガーされると、デフォルトの200 OK レスポンスが外部システムに返されます。
外部システムが特定のレスポンス形式を必要とする場合、成功レスポンスのステータスコードとレスポンスボディをカスタマイズできます。デフォルトのレスポンスは上書きされます。
- ステータスコード：[200, 399] の範囲内の任意のステータスコードをサポートします。
- レスポンスボディ：JSON またはプレーンテキストをサポートします。
返されるレスポンスボディでは、非 JSON コンテンツは自動的に JSON に変換されます。例えば、
OK は "message": "OK" としてラップされます。次のエラーレスポンスはシステム定義であり、カスタマイズできません。エラーの詳細はレスポンスボディで確認できます。
- 400 Bad Request
- 404 Not Found
- 413 Payload Too Large
- 500 Internal Server Error