Webhook トリガー¶

はじめに¶

Info:

トリガーは workflow アプリケーションでのみ利用可能です。

Webhook を使用すると、あるシステムが別のシステムにリアルタイムでデータを自動的に送信できます。特定のイベントが発生すると、ソースシステムはイベントの詳細を HTTP リクエストにパッケージ化し、宛先システムが提供する指定された URL に送信します。

同じ仕組みに従い、Webhook トリガーを使用すると、サードパーティのイベントに応答して workflow を実行できます。使用方法は次のとおりです：

workflow に Webhook トリガーを追加すると、一意の Webhook URL が生成されます。これは、外部 HTTP リクエストをリッスンする専用エンドポイントです。

Info:

    セルフホスティング環境では、`TRIGGER_URL`環境変数でこのURLのベースプレフィックスを変更できます。

    プレフィックスは外部システムからアクセス可能な公開ドメインまたはIPアドレスを指定してください。

この URL を使用して、外部システムで監視したいイベントをサブスクライブする Webhook を作成します。次に、Webhook トリガーを設定して、受信リクエストの処理方法とリクエストデータの抽出方法を定義します。

Note:

    テスト目的では、常にテスト Webhook URL を使用して、テストデータを本番データから分離してください。
    <img src="/images/test_webhook_url.png" alt="Test Webhook URL" width="563" />

サブスクライブしたイベントが発生すると、外部システムはイベントデータを含む HTTP リクエストを提供された Webhook URL に送信します。リクエストが正常に受信および処理されると、workflow がトリガーされ、指定されたイベントデータが変数として抽出され、ダウンストリームノードで参照できるようになります。

Tip:

対象の外部システムに既製のトリガープラグインがある場合は、代わりに[プラグイントリガー](/ja/use-flexai/nodes/trigger/plugin-trigger)を使用することをお勧めします。

Webhook トリガーの追加¶

workflow キャンバスで右クリックし、ブロックを追加 > 始める > Webhook トリガーを選択します。

Tip:

1 つの workflow は、並行して実行される複数の Webhook トリガーで開始できます。

並行分岐に同一の連続したノードが含まれている場合、共通セクションの前に[変数集約](/ja/use-flexai/nodes/variable-aggregator)ノードを追加して分岐をマージできます。これにより、各分岐で同じノードを個別に重複して追加することを回避できます。

Webhook トリガーの設定¶

Webhook トリガーが受信 HTTP リクエストを処理する方法を定義できます。以下が含まれます：

Webhook URL が期待する HTTP メソッド
リクエストのコンテンツタイプ
リクエストから抽出したいデータ
workflow が正常にトリガーされたときに外部システムに返送されるレスポンス

Note:

未公開の Webhook トリガーをテストするには、まず**このステップ実行**をクリックするか、workflow 全体をテスト実行する必要があります。これによりトリガーがリスニング状態になり、外部リクエストを受信できるようになります。そうしないと、リクエストはキャプチャされません。

HTTP メソッド¶

受信リクエストが正常に受信されるようにするには、Webhook URL が受け入れる HTTP メソッドを指定する必要があります。

ここで選択するメソッドは、外部システムがリクエストを送信するときに使用するメソッドと一致する必要があります。そうしないと、リクエストは拒否されます。

Tip:

通常、この情報は外部システムの Webhook ドキュメントまたはセットアップインターフェースで確認できます。

コンテンツタイプ¶

リクエストボディを適切に解析し、必要なデータを抽出できるようにするには、受信リクエストの期待されるコンテンツタイプを指定する必要があります。

ここで選択するコンテンツタイプは、外部システムから送信されるリクエストのコンテンツタイプと一致する必要があります。そうしないと、リクエストは拒否されます。

Query Parameters、Header Parameters、Request Body Parameters¶

受信リクエストの Query Parameters、Header Parameters、Request Body Parameters から特定のデータを抽出できます。抽出された各パラメータは、workflow で使用できる出力変数になります。

一部の外部システムは、各リクエストの配信ログを提供しており、リクエストに含まれるすべてのデータを表示し、どのパラメータを抽出するかを決定できます。

または、Webhook トリガーにテストリクエストを送信し、最後の実行ログで受信したリクエストデータを確認することもできます：

提供されたテスト Webhook URL を使用して、外部システムで Webhook を作成します。
トリガーで正しい HTTP メソッドとコンテンツタイプを設定します。
このステップ実行アイコンをクリックします。トリガーは外部リクエストのリスニングを開始します。
外部システムでサブスクライブしたイベントをトリガーして、提供された Webhook URL に HTTP リクエストを送信します。
トリガーの最後の実行タブに移動し、入力で受信したリクエストデータを確認します。

Note:

トリガーで定義する変数名は、リクエスト内の対応するパラメータのキー名と一致する必要があります。

Query Parameters:

    - 外部システムがリクエストを送信する際に Webhook URL（`?` の後）に追加するキーと値のペアのパラメータで、各ペアは `&` で区切られます。

    - 通常、イベントに関する単純で機密性のない識別子またはフィルタデータです。

    - 例：URL `{webhook url}?userID=u-456&source=email` から、`userID`（`u-456`）または `source`（`email`）を抽出できます。

Header Parameters:

    - リクエストヘッダーに含まれるリクエストメタデータ。

    - 認証トークンやリクエストボディのデータ形式など、リクエストを処理するために必要な技術情報。

    - 例：`Authorization: Bearer sk-abc...` や `Content-Type: application/json` などのヘッダーから、認証情報（`Bearer sk-abc...`）またはコンテンツタイプ（`application/json`）を抽出できます。

Request Body Parameters:

    - 顧客プロファイル、注文詳細、Slack メッセージの内容など、コアイベントデータが送信される主なペイロード。

    - 例：次のリクエストボディから、`customerName`（`Alex`）、アイテムのリスト、または `isPriority` ステータス（`true`）を抽出できます。

    ```json
    "customerName": "Alex",
    "items": 
    [
            { "sku": "A42", "quantity": 2 },
            { "sku": "B12", "quantity": 1 }
    ],
    "isPriority": true
    ```

Info:

        コンテンツタイプは、リクエストボディから抽出できるデータ型を決定します。

            | <div style={{width: '120px'}}>コンテンツタイプ</div> | `String` | `Number` | `Boolean` | `Object` | `File` | `Array[String]` | `Array[Number]` | `Array[Boolean]` | `Array[Object]` | `Array[File]` |
            |:--------------|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|
            | application/json | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
            | application/x-www-form-urlencoded | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
            | multipart/form-data | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
            | text/plain | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

パラメータ設定

抽出する各パラメータについて、次を指定できます：

変数名: リクエスト内のパラメータのキー名（例：userID=u-456 の userID）。

Note:

    Header Parameters の場合、変数名内のハイフン（`-`）は、出力変数でアンダースコア（`_`）に自動的に変換されます。

タイプ：期待されるデータ形式。Query Parameters と Request Body Parameters にのみ使用できます。Header Parameters は常に文字列として扱われます。
必須：workflow が適切に実行されるためにパラメータが必要かどうか。受信リクエストに必須パラメータが欠落している場合、workflow はトリガーされません。

レスポンス¶

ワークフローが外部HTTPリクエストによって正常にトリガーされると、デフォルトの 200 OK レスポンスが外部システムに返されます。

外部システムが特定のレスポンス形式を必要とする場合、成功レスポンスのステータスコードとレスポンスボディをカスタマイズできます。デフォルトのレスポンスは上書きされます。

ステータスコード：[200, 399] の範囲内の任意のステータスコードをサポートします。
レスポンスボディ：JSON またはプレーンテキストをサポートします。

Note:

返されるレスポンスボディでは、非 JSON コンテンツは自動的に JSON に変換されます。

例えば、`OK` は `"message": "OK"` としてラップされます。

Info:

次のエラーレスポンスはシステム定義であり、カスタマイズできません。エラーの詳細はレスポンスボディで確認できます。
    - 400 Bad Request
    - 404 Not Found
    - 413 Payload Too Large
    - 500 Internal Server Error

Webhook トリガーをテストする¶

未公開の Webhook トリガーをテストするには、まずこのステップ実行をクリックするか、workflow 全体をテスト実行する必要があります。これによりトリガーがリスニング状態になり、外部リクエストを受信できるようになります。そうしないと、受信リクエストはキャプチャされません。