| title | Webhook トリガー |
|---|
Webhook を使用すると、あるシステムが別のシステムにリアルタイムでデータを自動的に送信できます。特定のイベントが発生すると、ソースシステムはイベントの詳細を HTTP リクエストにパッケージ化し、宛先システムが提供する指定された URL に送信します。
同じ仕組みに従い、Webhook トリガーを使用すると、サードパーティのイベントに応答して workflow を実行できます。使用方法は次のとおりです：
-
workflow に Webhook トリガーを追加すると、一意の Webhook URL が生成されます。これは、外部 HTTP リクエストをリッスンする専用エンドポイントです。
セルフホスティング環境では、`TRIGGER_URL`環境変数でこのURLのベースプレフィックスを変更できます。プレフィックスは外部システムからアクセス可能な公開ドメインまたはIPアドレスを指定してください。 -
この URL を使用して、外部システムで監視したいイベントをサブスクライブする Webhook を作成します。次に、Webhook トリガーを設定して、受信リクエストの処理方法とリクエストデータの抽出方法を定義します。
テスト目的では、常にテスト Webhook URL を使用して、テストデータを本番データから分離してください。
-
サブスクライブしたイベントが発生すると、外部システムはイベントデータを含む HTTP リクエストを提供された Webhook URL に送信します。リクエストが正常に受信および処理されると、workflow がトリガーされ、指定されたイベントデータが変数として抽出され、ダウンストリームノードで参照できるようになります。
workflow キャンバスで右クリックし、ブロックを追加 > 始める > Webhook トリガーを選択します。
1 つのワークフローに複数の Webhook トリガーを含めることができます。これらのトリガーブランチが同じ下流ノードを共有する場合、[変数集約器](/ja/use-dify/nodes/variable-aggregator) を追加してそれらを集約し、各ブランチでノードを重複させないようにします。Webhook トリガーが受信 HTTP リクエストを処理する方法を定義できます。以下が含まれます：
-
Webhook URL が期待する HTTP メソッド
-
リクエストのコンテンツタイプ
-
リクエストから抽出したいデータ
-
workflow が正常にトリガーされたときに外部システムに返送されるレスポンス
受信リクエストが正常に受信されるようにするには、Webhook URL が受け入れる HTTP メソッドを指定する必要があります。
ここで選択するメソッドは、外部システムがリクエストを送信するときに使用するメソッドと一致する必要があります。そうしないと、リクエストは拒否されます。
通常、この情報は外部システムの Webhook ドキュメントまたはセットアップインターフェースで確認できます。リクエストボディを適切に解析し、必要なデータを抽出できるようにするには、受信リクエストの期待されるコンテンツタイプを指定する必要があります。
ここで選択するコンテンツタイプは、外部システムから送信されるリクエストのコンテンツタイプと一致する必要があります。そうしないと、リクエストは拒否されます。
受信リクエストの Query Parameters、Header Parameters、Request Body Parameters から特定のデータを抽出できます。抽出された各パラメータは、workflow で使用できる出力変数になります。
一部の外部システムは、各リクエストの配信ログを提供しており、リクエストに含まれるすべてのデータを表示し、どのパラメータを抽出するかを決定できます。
または、Webhook トリガーにテストリクエストを送信し、最後の実行ログで受信したリクエストデータを確認することもできます：
-
提供されたテスト Webhook URL を使用して、外部システムで Webhook を作成します。
-
トリガーで正しい HTTP メソッドとコンテンツタイプを設定します。
-
このステップ実行アイコンをクリックします。トリガーは外部リクエストのリスニングを開始します。
-
外部システムでサブスクライブしたイベントをトリガーして、提供された Webhook URL に HTTP リクエストを送信します。
-
トリガーの最後の実行タブに移動し、入力で受信したリクエストデータを確認します。
- 外部システムがリクエストを送信する際に Webhook URL（`?` の後）に追加するキーと値のペアのパラメータで、各ペアは `&` で区切られます。
- 通常、イベントに関する単純で機密性のない識別子またはフィルタデータです。
- 例：URL `{webhook url}?userID=u-456&source=email` から、`userID`（`u-456`）または `source`（`email`）を抽出できます。
</Tab>
<Tab title="Header Parameters">
- リクエストヘッダーに含まれるリクエストメタデータ。
- 認証トークンやリクエストボディのデータ形式など、リクエストを処理するために必要な技術情報。
- 例：`Authorization: Bearer sk-abc...` や `Content-Type: application/json` などのヘッダーから、認証情報（`Bearer sk-abc...`）またはコンテンツタイプ（`application/json`）を抽出できます。
</Tab>
<Tab title="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 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
</Info>
</Tab>
パラメータ設定
抽出する各パラメータについて、次を指定できます：
-
変数名: リクエスト内のパラメータのキー名（例：
Header Parameters の場合、変数名内のハイフン（`-`）は、出力変数でアンダースコア（`_`）に自動的に変換されます。userID=u-456のuserID）。 -
タイプ：期待されるデータ形式。Query Parameters と Request Body Parameters にのみ使用できます。Header Parameters は常に文字列として扱われます。
-
必須：workflow が適切に実行されるためにパラメータが必要かどうか。受信リクエストに必須パラメータが欠落している場合、workflow はトリガーされません。
ワークフローが外部HTTPリクエストによって正常にトリガーされると、デフォルトの 200 OK レスポンスが外部システムに返されます。
外部システムが特定のレスポンス形式を必要とする場合、成功レスポンスのステータスコードとレスポンスボディをカスタマイズできます。デフォルトのレスポンスは上書きされます。
-
ステータスコード：[200, 399] の範囲内の任意のステータスコードをサポートします。
-
レスポンスボディ：JSON またはプレーンテキストをサポートします。
例えば、`OK` は `"message": "OK"` としてラップされます。
未公開の Webhook トリガーをテストするには、まずこのステップ実行をクリックするか、workflow 全体をテスト実行する必要があります。これによりトリガーがリスニング状態になり、外部リクエストを受信できるようになります。そうしないと、受信リクエストはキャプチャされません。