---
pkg: '@nocobase/plugin-workflow-webhook'
title: "工作流触发器 - Webhook"
description: "Webhook 触发器：提供 HTTP URL 供第三方调用，支付回调、消息推送等外部系统触发工作流。"
keywords: "工作流,Webhook,HTTP 触发器,支付回调,外部系统调用,NocoBase"
---

# Webhook

## 简介

Webhook 触发器用于提供一个可被第三方系统通过 HTTP 请求调用的 URL，第三方事件发生时向该 URL 发送 HTTP 请求并触发流程执行。适用于外部系统发起通知，如支付回调、消息等。

## 创建工作流

创建工作流时，类型选择“Webhook 事件”：

![20241210105049](https://static-docs.nocobase.com/20241210105049.png)

:::info{title="提示"}
其中“同步”和“异步”工作流的区别在于，同步工作流会等待工作流执行完毕后再返回响应，而异步工作流则会直接返回触发器配置中已配置的响应，并在后台排队执行。
:::

## 触发器配置

![20241210105441](https://static-docs.nocobase.com/20241210105441.png)

### Webhook URL

Webhook 触发器的 URL 为系统自动生成，并绑定该工作流，可以点击右侧的按钮复制，并粘贴到第三方系统中。

其中 HTTP 方法仅支持 POST，其他方法会返回 `405` 错误。

### 安全

目前支持 HTTP 基本认证，可以通过开启该选项并设置用户名和密码，在第三方系统的 Webhook URL 中包含用户名和密码部分，以实现对 Webhook 的安全认证（标准详见：[MDN: HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme)）。

当设置了用户名和密码时，系统会校验请求中的用户名和密码是否匹配，未提供或不匹配时会返回 `401` 错误。

### 解析请求数据

第三方调用 Webhook 时，请求中携带的数据需要解析后才能在工作流中使用。解析后会作为触发器变量，在后续节点中可以引用。

对 HTTP 请求的解析分为三部分：

1.  请求头

    请求头通常都是简单的字符串类型的键值对，需要使用到的请求头字段可以直接配置。如 `Date`、`X-Request-Id` 等。

2.  请求参数

    请求参数即 URL 中的查询参数部分，如 `http://localhost:13000/api/webhook:trigger/1hfmkioou0d?query=1` 中的 `query` 参数。可以通过粘贴完整 URL 样例或者仅查询参数部分的样例，点击解析按钮来自动解析其中的键值对。

    ![20241210111155](https://static-docs.nocobase.com/20241210111155.png)

    自动解析会将 URL 中的参数部分转换为一个 JSON 结构，并根据参数层级生成 `query[0]`、`query[0].a` 等路径，该路径名称在不满足需求时可以手动修改，但通常无需修改。别名为在作为变量使用是的变量展示名称，为可选项。同时解析会生成样例中全量的参数表，如有不需要使用的参数，可以将其删除。

3.  请求体

    请求体即 HTTP 请求的 Body 部分，目前仅支持 `Content-Type` 格式为 `application/json` 的请求体。可以直接配置需要解析的路径，也可以输入 JSON 样例，点击解析按钮进行自动解析。

    ![20241210112529](https://static-docs.nocobase.com/20241210112529.png)

    自动解析会将 JSON 结构中的键值对转换为路径，如 `{"a": 1, "b": {"c": 2}}` 会生成 `a`、`b`、`b.c` 等路径。别名为在作为变量使用是的变量展示名称，为可选项。同时解析会生成样例中全量的参数表，如有不需要使用的参数，可以将其删除。

### 响应设置

Webhook 的响应部分在同步和异步的工作流中的配置方式有所不同，异步工作流直接在触发器中配置，在接收到 Webhook 请求后，会立即以触发器中的响应配置返回给第三方系统，再执行工作流；而同步的工作流则需要在流程中按业务需求通过添加响应节点来处理（详见：[响应节点](#响应节点)）。

通常情况异步触发的 Webhook 事件的响应的状态码为 `200`，响应体为 `ok`。也可以根据情况自定义响应的状态码、响应头和响应体。

![20241210114312](https://static-docs.nocobase.com/20241210114312.png)

## 响应节点

参考：[响应节点](../nodes/response.md)

## 示例

在 Webhook 工作流中，可以根据业务条件不同返回不同的响应，如下图：

![20241210120655](https://static-docs.nocobase.com/20241210120655.png)

通过条件分支节点，判断某个业务状态是否满足，如果满足则返回成功，否则返回失败。
