Webhooks（Webhooks（网络钩子））¶
A webhook is a concept in Data Connection that enables sending a request to an external system, such as Salesforce, SAP, or any configured HTTP server, typically to modify data in that external system.
By setting up a webhook and then configuring it for use in an action, you can send data to an external system when end users apply an action in Foundry. This enables workflows in Foundry to connect directly with source systems and write back data and decisions into those systems.
This section details the various options available for configuring webhooks in an action. For a step-by-step tutorial, see the documentation on how to add a webhook in an action.
Webhooks: Writeback vs. side effect¶
There are two ways that webhooks can be configured for use in an action: as a writeback or as a side effect.
For convenience, below is a table comparing the behavior of writeback and side effect webhooks.
| Type | When applied | Failure shown to end user? | Timing |
|---|---|---|---|
| Writeback | Before object changes | Yes | Before user sees success or failure |
| Side effect | After object changes | No | May be after user sees success message |
The following sections describe writeback webhooks and side effect webhooks in more detail.
Writeback webhooks¶
When configured as a writeback, the webhook will be executed before any other rules are evaluated; if the webhook execution fails, no other changes will be made. If you want to ensure that changes are not made in Foundry before the external system, you should set up your webhook as a writeback.
This behavior enables some degree of transactionality between Foundry and the external system. Using a writeback webhook guarantees that if the request to the external system fails, no changes will be applied to the Foundry Ontology. However, it is still possible that the external request may succeed but Ontology changes could fail.
Because the action stops being applied when a writeback webhook fails, you can only configure a single webhook as a writeback. If this webhook fails when the action is applied, an error will be shown to the end user describing the failure.
When a webhook is configured as a writeback, its output parameters can be used in subsequent rules. See the output parameters section below for more details.
Side effect webhooks¶
When configured as a side effect, a webhook will be executed after other rules are evaluated. This means that modifications to Foundry objects will occur before side effects are applied. You can configure multiple side effect webhooks in a single action, and they will be executed in no particular order. In an action with side effect webhooks, the end user will see a success message after Foundry objects are modified; executing the side effects may happen after the success message is shown.
If you need to call a webhook multiple times from a single action, this can be achieved with a side effect webhook by providing a list of payloads as an input. This will trigger the webhook as many times as there are payloads in the list provided and will be processed in no guaranteed order. An example of this can be found below in the input parameters section.
You should use side effect webhooks when you want to send best-effort notifications or write back to multiple external systems.
Input parameters¶
In order to configure a Webhook in an Action, you must populate all of its required input parameters. General reference material about Webhook input parameters is available in the Data Connection documentation.
There are two ways to configure Webhook input parameters: by mapping to Action parameters, or by using a Function.
When mapping to Action parameters, each required Webhook input must be set to either an Action parameter of the same type, a static value, or a property of an object parameter.
When using a Function, you must select a Function that returns a custom type that includes all of the required Webhook input parameters and strongly matches the Webhook type, otherwise you will receive an OntologyMetadata:ActionWebhookInputsDoNotHaveExpectedType error. Using a Function to populate Webhook input parameters can be useful when you want to use logic to populate inputs, especially if this logic is based on Ontology objects. For example, you can retrieve linked objects and pull property values from those objects to prepopulate Webhook inputs.
As an example, suppose you have a Webhook which takes three input parameters with IDs name, industry, and country:
You can write a Function that returns a custom interface of the same structure:
export interface MyWebhookInput {
name: string;
industry: string;
country: string;
}
Then, you can select this Function when configuring Webhook inputs in an Action, mapping Action parameters to the parameters required by the Function:
Below is a full code example of a Function that loads data from an Ontology object and uses it to populate Webhook inputs.
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,
}
}
}
A side effect Webhook may be called multiple times by returning a list of payloads from a Function. Below is an example Function which takes two companies as inputs, and returns a list containing two payloads matching the input parameters expected by a Webhook. If this Function is used from Actions to return the inputs for a side effect Webhook, it will result in two separate Webhook executions.
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,
}
];
}
}
Output parameters¶
When a Webhook is configured as a writeback Webhook, you can use its output parameters in subsequent rules. This is useful when the external system returns data that you want to immediately write into a Foundry object or use in a subsequent notification or side effect Webhook.
General reference material about Webhook output parameters is available in the Data Connection documentation.
To use an output parameter in a subsequent logic rule, select Writeback response when populating the value for a logic rule, then select the specific output you wish to use:
OAuth 2.0 authentication¶
When a webhook is configured on a REST API source that uses an outbound application for authentication, Foundry manages the OAuth 2.0 authorization flow on behalf of the user. Developers do not need to handle token acquisition or refresh. Foundry passes the correct access token with every webhook call.
For a full overview of OAuth 2.0 outbound application support across Foundry workflows, see the OAuth 2.0 outbound applications documentation.
中文翻译¶
# Webhooks（网络钩子）
[Webhook](https://palantir.com/docs/foundry/data-connection/webhooks-overview/) 是 Data Connection 中的一个概念，用于向外部系统（如 Salesforce、SAP 或任何已配置的 HTTP 服务器）发送请求，通常是为了修改该外部系统中的数据。
通过设置 webhook 并将其配置为在操作中使用，当最终用户在 Foundry 中应用操作时，您可以将数据发送到外部系统。这使得 Foundry 中的工作流能够直接与源系统连接，并将数据和决策写回这些系统。
本节详细介绍了在操作中配置 webhook 时可用的各种选项。有关分步教程，请参阅[如何在操作中添加 webhook](https://palantir.com/docs/foundry/action-types/set-up-webhook/) 的文档。
## Webhooks：写回与副作用
Webhook 在操作中有两种配置方式：作为**写回（writeback）**或作为**副作用（side effect）**。
<img src="./media/webhooks-add-webhook.png" alt="添加 webhook" width="400" />
为方便起见，下表比较了写回 webhook 和副作用 webhook 的行为。
| 类型 | 何时应用 | 是否向最终用户显示失败？ | 时机 |
|--- |--- |--- |--- |
| **写回** | 在对象更改之前 | 是 | 在用户看到成功或失败之前 |
| **副作用** | 在对象更改之后 | 否 | 可能在用户看到成功消息之后 |
以下各节将更详细地描述写回 webhook 和副作用 webhook。
### 写回 Webhooks
当配置为**写回**时，webhook 将在*任何*其他规则评估*之前*执行；如果 webhook 执行失败，则不会进行任何其他更改。如果您希望在外部系统更改之前确保 Foundry 中不发生更改，则应将 webhook 设置为写回。
这种行为使得 Foundry 与外部系统之间具有一定程度的事务性。使用写回 webhook 可以保证，如果向外部系统的请求失败，则不会对 Foundry 本体论（Ontology）应用任何更改。但是，外部请求可能成功，而本体论（Ontology）更改仍有可能失败。
由于当写回 webhook 失败时，操作会停止应用，因此您只能将一个 webhook 配置为写回。如果此 webhook 在应用操作时失败，将向最终用户显示一条描述失败的错误消息。
当 webhook 配置为写回时，其输出参数可以在后续规则中使用。有关更多详细信息，请参阅下面的[输出参数](#output-parameters)部分。
### 副作用 Webhooks
当配置为**副作用**时，webhook 将在*其他*规则评估*之后*执行。这意味着对 Foundry 对象的修改将在应用副作用之前发生。您可以在单个操作中配置多个副作用 webhook，它们将按任意顺序执行。在具有副作用 webhook 的操作中，最终用户将在 Foundry 对象修改后看到成功消息；执行副作用可能发生在显示成功消息之后。
如果您需要从单个操作多次调用 webhook，可以通过提供一个有效负载列表作为输入来实现副作用 webhook。这将触发 webhook，触发次数等于提供的列表中的有效负载数量，并且处理顺序不保证。下面在[输入参数](#input-parameters)部分可以找到此示例。
当您想要发送尽力而为的通知或写回多个外部系统时，应使用副作用 webhook。
## 输入参数
为了在操作中配置 Webhook，您必须填充其所有必需的输入参数。有关 Webhook 输入参数的一般参考材料，请参阅 [Data Connection 文档](https://palantir.com/docs/foundry/data-connection/webhooks-reference/#input-parameters)。
有两种配置 Webhook 输入参数的方法：映射到操作参数，或使用函数。
当映射到**操作参数**时，每个必需的 Webhook 输入必须设置为相同类型的操作参数、静态值或对象参数的属性。
<img src="./media/webhooks-input-parameters.png" alt="输入参数" width="400" />
当使用[函数](https://palantir.com/docs/foundry/functions/overview/)时，您必须选择一个返回自定义类型的函数，该类型包含所有必需的 Webhook 输入参数并与 Webhook 类型强匹配，否则您将收到 `OntologyMetadata:ActionWebhookInputsDoNotHaveExpectedType` 错误。当您想使用逻辑来填充输入时，使用函数填充 Webhook 输入参数非常有用，尤其是当此逻辑基于本体论（Ontology）对象时。例如，您可以检索链接对象并从这些对象中提取属性值以预填充 Webhook 输入。
例如，假设您有一个 Webhook，它接受三个 ID 分别为 `name`、`industry` 和 `country` 的输入参数：
<img src="./media/webhooks-input-parameters-example.png" alt="输入参数示例" width="400" />
您可以编写一个返回相同结构自定义接口的函数：
```typescript
export interface MyWebhookInput {
name: string;
industry: string;
country: string;
}
然后，在操作中配置 Webhook 输入时，您可以选择此函数，将操作参数映射到函数所需的参数：
下面是一个函数的完整代码示例，该函数从本体论（Ontology）对象加载数据并使用它来填充 Webhook 输入。
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。下面是一个示例函数，它接受两个公司作为输入，并返回一个包含两个有效负载的列表，这些有效负载与 Webhook 期望的输入参数匹配。如果从操作中使用此函数来返回副作用 Webhook 的输入，则将导致两次独立的 Webhook 执行。
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 身份验证¶
当 webhook 配置在使用出站应用程序进行身份验证的 REST API 源上时，Foundry 代表用户管理 OAuth 2.0 授权流程。开发人员无需处理令牌获取或刷新。Foundry 在每次 webhook 调用时传递正确的访问令牌。
有关 Foundry 工作流中 OAuth 2.0 出站应用程序支持的完整概述，请参阅 OAuth 2.0 出站应用程序文档。 ```