Webhook

Webhook は Data Connection の概念で、Salesforce、SAP、設定済みの HTTP サーバーなどの外部システムにリクエストを送信できます。通常は、その外部システムのデータを変更するために使用します。

Webhook をセットアップし、アクションで使用するように設定すると、エンドユーザーが Foundry でアクションを適用したときに外部システムへデータを送信できます。これにより、Foundry のワークフローをソースシステムに直接接続し、データや意思決定をそれらのシステムに書き戻せます。

このセクションでは、アクションで Webhook を設定する際に利用可能なさまざまなオプションについて詳しく説明します。手順を追って進めるチュートリアルについては、アクションに Webhook を追加する方法のドキュメントを参照してください。

Webhook：ライトバックと副次的効果

アクションで使用する Webhook には、書き戻しまたは副次的効果の2つの設定方法があります。

比較しやすいように、ライトバック Webhook と副次的効果 Webhook の動作を以下のテーブルにまとめます。

以降のセクションでは、ライトバック Webhook と副次的効果 Webhook についてさらに詳しく説明します。

ライトバック Webhook

書き戻しとして設定した場合、Webhook はほかのルールが評価される前に実行されます。Webhook の実行に失敗した場合、ほかの変更は行われません。外部システムより先に Foundry で変更が行われないようにするには、Webhook をライトバックとしてセットアップしてください。

この動作により、Foundry と外部システムの間で、ある程度のトランザクション性を確保できます。ライトバック Webhook を使用すると、外部システムへのリクエストに失敗した場合、Foundry オントロジーには変更が適用されないことが保証されます。ただし、外部リクエストに成功しても、オントロジーの変更に失敗する可能性はあります。

ライトバック Webhook に失敗するとアクションの適用が停止するため、ライトバックとして設定できる Webhook は1個だけです。アクションの適用時にこの Webhook に失敗すると、失敗の内容を説明するエラーがエンドユーザーに表示されます。

Webhook をライトバックとして設定すると、その出力パラメーターを後続のルールで使用できます。詳細については、以下の出力パラメーターのセクションを参照してください。

副次的効果 Webhook

副次的効果として設定した場合、Webhook はほかのルールが評価された後に実行されます。つまり、副次的効果が適用される前に Foundry オブジェクトが変更されます。1個のアクションに複数の副次的効果 Webhook を設定でき、それらは特定の順序なしに実行されます。副次的効果 Webhook を含むアクションでは、Foundry オブジェクトが変更された後にエンドユーザーに成功メッセージが表示されます。副次的効果の実行は、成功メッセージが表示された後になる場合があります。

1個のアクションから Webhook を複数回呼び出す必要がある場合は、ペイロードのリストを入力として指定することで、副次的効果 Webhook で実現できます。指定したリストに含まれるペイロードの数だけ Webhook がトリガーされ、処理の順序は保証されません。この例は、以下の入力パラメーターのセクションにあります。

ベストエフォートで通知を送信したい場合や、複数の外部システムにライトバックしたい場合は、副次的効果 Webhook を使用してください。

入力パラメーター

アクションで Webhook を設定するには、必須の入力パラメーターをすべて設定する必要があります。Webhook の入力パラメーターに関する一般的なリファレンス資料は、Data Connection のドキュメントで参照できます。

Webhook の入力パラメーターを設定する方法は、アクションパラメーターへのマッピングと、関数の使用の2つです。

アクションパラメーターにマッピングする場合、Webhook の必須入力はそれぞれ、同じデータ型のアクションパラメーター、固定値、またはオブジェクトパラメーターのプロパティのいずれかに設定する必要があります。

関数を使用する場合は、Webhook の必須入力パラメーターをすべて含み、Webhook のデータ型に厳密に一致するカスタム型を返す関数を選択する必要があります。そうでない場合は、OntologyMetadata:ActionWebhookInputsDoNotHaveExpectedType エラーが発生します。Webhook の入力パラメーターを関数で設定する方法は、ロジックを使用して入力を設定したい場合、特にそのロジックがオントロジーのオブジェクトに基づく場合に便利です。たとえば、リンクされたオブジェクトを取得し、それらのオブジェクトからプロパティ値を取り出して、Webhook の入力を事前入力できます。

例として、ID が name、industry、country の3個の入力パラメーターを受け取る Webhook があるとします。

同じ構造のカスタムインターフェースを返す関数を作成できます。

Copied!
1
2
3
4
5
export interface MyWebhookInput {
    name: string;
    industry: string;
    country: string;
}

次に、アクションで Webhook の入力を設定する際にこの関数を選択し、アクションパラメーターを関数に必要なパラメーターにマッピングできます。

以下は、オントロジーのオブジェクトからデータを読み込み、そのデータを使用して Webhook の入力を設定する関数の完全なコード例です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Function, UserFacingError } from "@foundry/functions-api";
import { Company } from "@foundry/ontology-api";

export interface MyWebhookInput {
    name: string;
    industry: string;
    country: string;
}

export class MyWebhookFunctions {
    @Function()
    public returnWebhookInput(company: Company): MyWebhookInput {
        if (!company.name || !company.industry || !company.country) {
            throw new UserFacingError("Some required fields are not set.");
        }
        return {
            name: company.name,
            industry: company.industry,
            country: company.country,
        }
    }
}

関数からペイロードのリストを返すことで、副次的効果 Webhook を複数回呼び出せます。以下は、2社を入力として受け取り、Webhook が期待する入力パラメーターに一致する2個のペイロードを含むリストを返す関数の例です。この関数をアクションから使用して副次的効果 Webhook の入力を返すと、Webhook が個別に2回実行されます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { Function } from "@foundry/functions-api";
import { Company } from "@foundry/ontology-api";

export interface MyWebhookInput {
    arg1: string;
    arg2: string;
}

export class MyFunctions {
    @Function()
    public createWebhookRequest(company1: Company, company2: Company): MyWebhookInput[] {
        return [
        {
           arg1: company1.someProperty,
           arg2: company1.someOtherProperty,
        },
        {
           arg1: company2.someProperty,
           arg2: company2.someOtherProperty,
        }
        ];
    }
}

出力パラメーター

Webhook をライトバック Webhook として設定すると、その出力パラメーターを後続のルールで使用できます。これは、外部システムが返すデータをすぐに Foundry オブジェクトに書き込んだり、後続の通知や副次的効果 Webhook で使用したりしたい場合に便利です。

Webhook の出力パラメーターに関する一般的なリファレンス資料は、Data Connection のドキュメントで参照できます。

後続のロジックルールで出力パラメーターを使用するには、ロジックルールの値を設定する際に書き戻し応答を選択し、次に使用する出力を選択します。

OAuth 2.0 認証

認証にアウトバウンドアプリケーションを使用する REST API ソースに Webhook を設定した場合、Foundry はユーザーに代わって OAuth 2.0 の認可フローを管理します。開発者がトークンの取得や更新を処理する必要はありません。Foundry は、すべての Webhook 呼び出しで適切なアクセストークンを渡します。

Foundry のワークフロー全体における OAuth 2.0 アウトバウンドアプリケーションのサポートの概要については、OAuth 2.0 アウトバウンドアプリケーションのドキュメントを参照してください。