Skip to main content

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。

Info

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

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

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

  1. ワークフローに Webhook トリガーを追加すると、一意の Webhook URL が生成されます。これは、外部 HTTP リクエストをリッスンする専用エンドポイントです。この URL は Dify Cloud のドメイン上でホストされ、外部システムから公開された形でアクセスできます。

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

    Note

    テスト目的では、常にテスト Webhook URL を使用して、テストデータを本番データから分離してください。

    Webhook URL をテスト

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

Tip

対象の外部システムに既製のトリガー統合がある場合は、代わりに インテグレーショントリガー を使用することを検討してください。

Webhook トリガーの追加#

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

Tip

1 つのワークフローに複数の Webhook トリガーを含めることができます。これらのトリガーブランチが同じ下流ノードを共有する場合、変数集約器 を追加してそれらを集約し、各ブランチでノードを重複させないようにします。

Webhook トリガーの設定#

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

  • Webhook URL が期待する HTTP メソッド

  • リクエストのコンテンツタイプ

  • リクエストから抽出したいデータ

  • ワークフローが正常にトリガーされたときに外部システムに返送されるレスポンス

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 トリガーにテストリクエストを送信し、最後の実行ログで受信したリクエストデータを確認することもできます：

  1. 提供されたテスト Webhook URL を使用して、外部システムで Webhook を作成します。

  2. トリガーで正しい HTTP メソッドとコンテンツタイプを設定します。

  3. このステップ実行 アイコンをクリックします。トリガーは外部リクエストのリスニングを開始します。

  4. 外部システムでサブスクライブしたイベントをトリガーして、提供された Webhook URL に HTTP リクエストを送信します。

  5. トリガーの 最後の実行 タブに移動し、入力 で受信したリクエストデータを確認します。

Note

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

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

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

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

パラメータ設定

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

  • 変数名：リクエスト内のパラメータのキー名（例：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 全体をテスト実行する必要があります。これによりトリガーがリスニング状態になり、外部リクエストを受信できるようになります。そうしないと、受信リクエストはキャプチャされません。