核心功能
- 公开 API 端点，支持通过 HTTP POST 和 PUT 进行数据摄取，并采用现代身份验证机制
- 基于用户的速率限制和并发请求管理，并支持 CORS
- 采用 HMAC 签名身份验证以增强安全性，并支持自定义响应事件脚本
- 提供示例请求模板，用于 XML Map 端口集成和工作流自动化
概述
Webhook 端口使数据能够通过 HTTP POST 和 PUT 进入 知行之桥 工作流。每个 Webhook 端口在应用程序中公开一个接口，外部客户端可以向该接口发送 XML 和 JSON 负载。这些负载将写入输出文件，并发送到工作流中下一连接的端口。 可以在 Webhook 端口中指定示例请求，以简化 POST 到端点的数据转换流程。指定 XML 示例后，将 Webhook 端口连接到流程中的 XML Map 端口，XML Map 端口会自动检测发布到端点的 XML 文件的预期结构。然后，可以使用 XML Map 端口的节点值编辑器将此结构映射到目标 XML 结构。端口配置
本节包含所有可配置的端口属性。设置选项卡
端口设置
与端口的核心操作相关的设置。高级设置
请求详情选项卡
提供一个 XML 或 JSON 模板，表示传入数据的预期结构。指定示例请求的主要好处是将 Webhook 端口连接到工作流中的 XML Map 端口。当 API 数据需要转换为其他格式（例如 EDI 报文或数据库插入）时，应使用 XML Map 端口。 XML Map 端口会检测示例请求的 XML 结构，并将其用作 XML Map 端口的源文件。将代表目标格式的 XML 结构上传为目标文件，然后使用节点值编辑器将源结构转换为目标结构。用户选项卡
用户选项卡可让您：- 创建用户及其关联的 authtoken 和 OAuth 2.0 凭据
- 定义 POST 和/或 PUT 权限
- 指定每个用户每小时可以发出多少个请求
- 指定允许多少个并发请求
此处的请求设置会覆盖服务器选项卡的默认速率限制部分中的设置。
服务器选项卡
受信任的 IP 地址
默认速率限制／用户
如果”用户”选项卡上未提供值，则限制允许的请求数量的设置。跨域资源共享 (CORS)
管理使用 CORS 来服务跨域资源的设置。| 设置 | 描述 |
|---|---|
| 启用跨源资源共享 (CORS) | 是否启用 CORS。仅当选中此框时，其余选项才可用。 |
| 允许所有不带 '*' 的域 | 如果启用，域来源不限于特定列表。 |
| Access-Control-Allow-Origin | 要允许的以逗号分隔的域来源列表。作为 HTTP 响应消息头包含在内。 |
| Access-Control-Allow-Credentials | 跨域请求中是否允许用户凭据（例如 cookie）。作为 HTTP 响应消息头包含在内。 |
| Access-Control-Allow-Methods | 允许的以逗号分隔的方法列表。作为 HTTP 响应消息头包含在内。 |
| Access-Control-Allow-Headers | 允许的消息头的逗号分隔列表。作为 HTTP 响应消息头包含在内。 |
| Access-Control-Max-Age | 可以缓存 Access-Control 响应消息头值的最大持续时间（以秒为单位）。 |
高级设置
高级选项卡
消息
消息设置确定端口如何搜索消息并在处理后管理它们。
| 设置 | 描述 |
|---|---|
| 保存到已发送文件夹 | 选中此项可将端口处理的文件复制到该端口的“已发送”文件夹中。 |
| 已发送文件夹方案 | 端口根据选定的时间间隔对 已发送 文件夹中的文件进行分组。例如，Weekly 选项指示端口每周创建一个新的子文件夹，并将本周发送的所有文件存储在该文件夹中。空白设置告诉端口将所有文件直接保存在 已发送 文件夹中。对于处理许多事务的端口，使用子文件夹可以帮助保持文件有序并提高性能。 |
日志
用于管理日志创建和存储的设置。
| 设置 | 描述 |
|---|---|
| 日志级别 | 指定要记录在端口日志目录中的信息类型：
|
| 日志文件夹结构 | 指示端口根据选定的时间间隔将日志文件夹中的文件分组。例如，Weekly 选项指示端口每周创建一个新的子文件夹，并将该周的所有日志存储在该文件夹中。空白设置告诉端口将所有日志直接保存在日志文件夹中。对于处理许多事务的端口，使用子文件夹有助于保持日志的有序性并提高性能。 |
| 保留消息副本 | 指示端口在日志目录中保存最新消息副本的切换。请注意，端口每个子文件夹只保留一个消息，并且端口在再次运行时会覆盖以前保存的消息。 |
其他
特殊设置适用于特定用例。
| 设置 | 描述 |
|---|---|
| 其他设置 | 允许在以分号分隔的列表中配置隐藏的端口设置，例如 setting1=value1;setting2=value2。正常的端口用例和功能不需要使用这些设置。 |
告警选项卡
SLA 选项卡
HMAC 身份验证
HMAC（基于哈希的消息认证码）签名身份验证是一种加密方法，用于验证 Webhook 请求的真实性和完整性。它使用共享密钥为每个请求生成唯一的签名，从而确保：- 请求真实性：确认请求来自可信来源
- 数据完整性：验证请求负载在传输过程中未被篡改
- 重放攻击防护：防止拦截的请求被恶意重用
配置
- 启用 HMAC 身份验证
- 在 Webhook 端口设置中勾选启用 HMAC 身份验证。
- （可选）自定义 HMAC 签名标头值（默认值为
x-cdata-hmac-signature）。
为用户设置 HMAC 密钥
启用 HMAC 身份验证后：- 导航至 Webhook 端口的用户选项卡。
- 为每个授权的 Webhook 用户配置 HMAC 密钥：
- 系统会为每个用户自动生成一个 HMAC 密钥。您可以使用自定义值覆盖自动生成的密钥。每个用户必须使用分配的 HMAC 密钥为其 Webhook 请求生成有效的签名。
Auth Token 身份验证
用户可以通过在请求中提供 authtoken 来访问 Webhook 资源。通过在用户选项卡上添加或编辑用户并导航到身份验证选项卡来管理用户和 authtoken。 在用户调用 Webhook 接口之前，还必须设置连接的受信任 IP 地址。在服务器选项卡的受信任的 IP 地址部分中进行设置。默认情况下，所有 IP 地址均受限制。在基本身份认证中使用身份认证令牌
使用基本身份认证时，应将用户的 authtoken 用作密码。在 HTTP 头部中使用认证令牌
将 HTTP 头部x-{companyName}-authtoken 与 authtoken 一起添加为 HTTP 请求的一部分。
使用身份认证令牌作为查询字符串参数
要允许端口在查询字符串参数中传递 authtoken，请在服务器选项卡的高级设置部分中勾选 Allow authtoken in URL。 启用此功能后，可以将 authtoken 指定为@authtoken 参数的值，该参数可以作为 HTTP 表单数据或查询参数的一部分提供。
OAuth 2.0 身份验证
用户可以使用 OAuth 2.0 身份验证来保护 Webhook 资源。通过在用户选项卡上添加或编辑用户并导航到身份验证选项卡来管理用户和 OAuth 凭据。接收数据
将数据上传到 Webhook 接口时，Web 请求的主体将作为输出文件写入并发送到工作流中下一个连接的端口。这允许使用灵活的方法通过调用外部 API 来调用 知行之桥 工作流。自定义响应
通常，Webhook 端口接受带有请求已接受的令牌响应的发布数据，但可以使用Response 事件自定义响应，其中 _request、_httpheaders、_response 和 _message 特殊项目可用。指定后，端口期望通过 _response 项提供自定义响应。
您还可以使用 Response 事件，通过以下属性推送自定义输出项：
- Filename：传递到下游工作流的输出消息文件名。
- Data：包含在传递到下游工作流的消息中的数据。对于二进制数据，请改用 Base64Data 属性。
- Base64Data：包含在传递到下游工作流的消息中的 Base64 编码数据。
- HeaderNames#：包含在传递到下游工作流的消息中的标头名称列表。使用 HeaderValues 属性在匹配的索引处指定这些标头的值。
- HeaderValues#：包含在传递到下游工作流的消息中的标头值列表。这些值用于 HeaderNames 列表中相同索引处定义的标头名称。
- Logs#：包含在事务日志中的日志条目列表。
示例
若要将包含 Webhook 请求正文的文件（带有自定义文件名和标头）推送到下游工作流中，Response 事件中的 ArcScript 可能如下所示：
Response 事件中的 ArcScript 可能如下所示：
Response 事件，客户端可以发送类似于以下内容的请求：