Webhook | Weegloo Docs

设想您经营一家服装网店。每次上架新商品时，都有一些必须亲手处理的后续工作。比如把商品说明翻译成其他国家的语言，或是把上架这件事通知到公司内部的即时通讯工具里。这些后续工作不必每次都靠人手去做，您可以让系统在商品上架的那一刻，自动通知外部的某个程序来代为处理。这种“某件事发生时就自动通知到预先指定的地方”的装置，就是 Webhook。

可以把它比作装在店门上的门铃。客人推门进来时（商品被上架时），门铃会自动响起，里面的店员（外部程序）一听到“有客人来了”就立刻开始行动。不需要有人一直守在门口盯着。Webhook 就像那只门铃，在预定的事件发生的那一刻，自动开始您预定的动作。

本页先来看 Webhook 是什么、在什么情况下使用，然后在服装店 Space 里亲手创建一个 Webhook。

Webhook 做的事

Webhook 由预先设定的三件事构成。

何时：设定在什么事件发生时作出反应。例如可以设为“商品（Content）被新建时”。
要做什么：二者选其一。向外部程序的互联网地址（URL）发送请求，或运行在 Space 内创建的 Script。
开启还是关闭：设定现在要开启这个 Webhook（Active），还是暂时关闭它（Inactive）。关闭后，即使预定的事件发生，也什么都不会发生。

当预定的事件实际发生时，Webhook 会执行您预定的动作。当它发送到外部地址时，请求中会带上诸如发生了什么事、是在哪个商品上发生的之类的信息。收到请求的外部程序会根据这些信息去做自己的工作。

哪些变化会触发请求

触发请求的“事件”，是 Space 内的资源所发生的变化。您可以选择诸如商品这样的 Content、上传的文件 Media、作为模板的 Content Type 上发生某事时的情况。

每种资源可选的变化如下。

变化	何时发生	服装店示例
Create	被新建时	上架新商品
Save	修改内容并保存时	修改并保存商品说明
Delete	被删除时	删除已停产的商品
Publish	发布并对外公开时	把商品公开到网站
Unpublish	取消发布时	把缺货商品从网站撤下
Archive	进行归档时	把过季商品归档
Unarchive	解除归档时	把归档的商品恢复

例如“每当有新商品上架时就发送请求”，就是选择“商品（Content）的 Create”。

一个 Webhook 也可以同时选择多种变化。如果同时选择“商品被新建时”和“商品被修改时”，那么这两者中任何一个发生，请求都会发出。

加条件来收窄范围

有时即使选中的变化发生了，您也不希望每次都发送请求。例如您可能只想在“不是所有 Content，而是用‘商品’模板创建的 Content 被新建时”才接收。这时就用筛选来收窄发送请求的情形。

一条筛选由“以什么为基准、如何比较”这样一行构成。以什么为基准来过滤，要从四项中选择。

是用哪个模板创建的项目：例如只向用“商品” Content Type 创建的 Content 发送请求。这是最常用的条件。
是否为某个特定项目：只对在某个指定项目上发生的变化发送请求。
是谁创建的项目：只对特定的人创建的项目发送请求。
是谁最后修改的项目：只对特定的人最后修改过的项目发送请求。

同时也要选择比较的方式。可以收窄为：仅当与设定值相等时、仅当不相等时、仅当属于设定的多个值之一时、仅当不属于其中任何一个时，或仅当符合或不符合设定格式（模式）时。

在内容工作室的触发器设置中，用 添加筛选 逐行添加条件。设置多条筛选时，只有全部满足这些条件的情况才会发送请求；一条都不设时，则每当选中的变化发生时就发送请求。

按外部程序想要的格式发送

如果不另行设定，请求中会原样带上发生变化的那个项目的全部信息。例如商品“不锈钢保温杯 500ml”被新建时，请求中带去的内容大致是这样的形状。

{
  "sys": { "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq", "type": "Content" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
  }
}

（实际上会带上更多信息，上面只是摘取的一部分。）外部程序从中挑选自己需要的值来用即可。但也有一些程序规定了“只接收这种格式”。这种情况下，就在内容工作室的 Payload 中选择 自定义 Webhook payload，自己写下要发送的格式。

Webhook 创建画面的请求头与 Payload 区域。已开启包含请求正文并选中自定义 Webhook payload，在下方的 JSON 编辑器中写下要发送的格式

写下要发送的格式时，在需要从上面的数据中取值填入的地方使用占位符。占位符的形状为 { /payload/… }。这里的 payload 指的就是上面展示的那个项目整体，其后的路径用来精确定位想要的值。

{ /payload/sys/id } → 上面数据中 sys 内的 id（商品的唯一编号）
{ /payload/fields/productName/ko-KR } → fields 内 productName 的 ko-KR（韩语商品名）。fields/ 之后依次接 Field 的 ID（商品名即 productName）和语言代码（韩语即 ko-KR）。

例如翻译程序要求“按这种格式给出待翻译的文本和商品编号”，那么就这样写 payload。

{
  "id": "{ /payload/sys/id }",
  "text": "{ /payload/fields/productName/ko-KR }"
}

这样一来，保温杯商品被新建的那一刻，占位符会被替换为实际的值，按如下形式发送。

{
  "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
  "text": "스테인리스 텀블러 500ml"
}

同样的占位符也可以放进发送地址（URL）或请求头的值里，发送的方式（method）和格式（JSON 或表单格式）也可以一并选择。如果指向的路径上没有值，那个位置就会变成空值。

像外部 API 密钥这种不能让别人看到的值，在添加请求头时把它的类型设为 Secret。这样该值就会被遮蔽后保存，不会暴露给最终用户。

添加请求头时打开类型下拉菜单的样子。从 Secret、HTTP Basic Auth、Custom 中选择

用 Script 代替 URL 执行

到目前为止，讲的都是 Webhook 向外部地址（URL）发送请求的情形。Webhook 也可以改为运行在 Space 内创建的 Script。Script 是一种不向外部发出、而在 Space 内代为执行预定作业（创建、修改资源等）的装置。当您想不经过外部程序、直接在 Space 内完成后续工作时，就用这种方式。

一个 Webhook 在“向外部地址发送”和“运行 Script”两者中，恰好只做其中一件。这在创建画面的 请求目标 中设定。选择 直接输入 URL 后，就会像前面那样向地址发送请求；若改为在列表中选择一个 Script，则会运行那个 Script。

选择 Script 后，还会一并出现用于决定该 Script 以谁的身份运行的 Run as。从两者中选择其一。

Webhook 的创建者（默认）：运行过程中被创建或改变的资源，其“创建者”会记为创建该 Webhook 的人。
触发的用户：记为引发该变化的用户。

这项设定只决定资源上留下的“是谁做的”标记，并不会扩大或收窄 Script 能做的事。Script 能做的事的范围，在创建该 Script 时就已确定。

实际选择的步骤如下。

在创建画面点击 请求目标。
在列表中选择要运行的 Script。这是用 Script 来代替 直接输入 URL。
在 Run as 中选择身份。默认是 Webhook 的创建者。

在 Webhook 创建画面把「填充商品说明」 Script 选为请求目标的状态。填好的调用 URL 与 Run as 的两个选项（Webhook 的创建者、触发的用户）一起显示

Script 是什么、如何创建，请参见 Script。

创建服装店 Webhook

现在来在服装店 Space 里创建一个 Webhook。这是一个“新商品被上架时，就把这件事通知给预先准备好的外部翻译程序”的 Webhook。接收请求的外部程序的地址就设为 https://example.com/translate。

在服装店 Space 的设置中打开 Webhook 画面。
按右上角的创建按钮。
在名称栏中输入 新商品翻译通知。这个名称是为了日后辨认这是哪个 Webhook。
设定要发送请求的变化。如果只想对特定变化发送，就选择选择特定触发事件后指定想要的变化（这里是商品（Content）的 Create）；如果想对所有变化都发送，就选择为所有事件触发。
在 URL 栏中输入接收请求的外部程序的地址 https://example.com/translate。
开启启用后，创建完成的瞬间就会发送请求（Active）。如果只想暂时试一下，就把它关闭（Inactive）。
按创建按钮来创建 Webhook。

新建 Webhook 画面。已填入名称、启用、触发器选择、URL 的样子

当列表中出现处于 Active 状态的 新商品翻译通知 时，Webhook 就创建好了。

Webhook 列表中显示处于 Active 状态的“新商品翻译通知”的画面

创建之后，请在服装店实际上架一个新商品试试。上架的那一刻，Webhook 就会向填入的地址发送请求。请求是否成功送达、外部程序如何响应，都可以在 Webhook 的调用记录中查看。

开启关闭与修改

Webhook 创建之后也可以随时开启和关闭。想暂时停止发送请求时，不要删除，而是把它关闭为 Inactive。关闭期间，即使上架新商品也不会发送请求。再次开启为 Active 后，就会从那时起重新发送请求。

重新打开已创建的 Webhook 后，可以关闭或重新开启启用。名称、要发送请求的地址、要触发的变化等内容日后也可以修改；不再使用的 Webhook 删除即可。

接下来要做的事

Content 建模：介绍如何创建“商品”这类 Content 的模板，它正是 Webhook 触发请求的对象。
编写 Content：可以实际上架商品，确认 Webhook 是否正常运作。
Script：介绍如何创建可供 Webhook 代替 URL 执行的、在 Space 内运行的作业。
API 参考：介绍在程序中直接创建和管理 Webhook 时所用的请求、响应格式和字段规范。