API参考：Webhooks

出站Webhook会在ProcessMind内部发生事件时通知您的系统。每次投递都会使用您的Webhook密钥签名，并以JSON POST发送：X-ProcessMind-Signature标头包含sha256=<hex>，即原始请求正文的HMAC-SHA256值。请根据收到的确切字节验证签名（解析JSON之前），并拒绝签名不匹配的投递。每个正文还包含deliveryId，您可以使用它对至少一次投递进行去重。

列出出站Webhook

端点： GET /v1/tenant/{tenantId}/webhooks

**身份验证：**租户范围API密钥 · read作用域

参数：

名称	类型	位置	必填	描述
tenantId	string	路径	是	格式：uuid
limit	integer	查询	否	返回的最大项目数
offset	integer	查询	否	跳过的项目数

响应（200）：

Webhook列表

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"url": "string",
		"events": [
			"process.created"
		],
		"description": "string",
		"isActive": true,
		"createdAt": "2024-03-15T16:30:00Z"
	}
]

错误：

• 401缺少、无效、已禁用或已过期的API密钥

创建出站Webhook（仅返回一次签名密钥）

端点： POST /v1/tenant/{tenantId}/webhooks

**身份验证：**租户范围API密钥 · write作用域

参数：

名称	类型	位置	必填	描述
tenantId	string	路径	是	格式：uuid

请求正文：

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string"
}

字段	类型	必填	描述
url	string	是	接收签名POST投递的公开https端点（不支持私有地址或回环地址）
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	是	触发向此Webhook投递的事件
description	string	否	可选描述 最大长度：500

响应（201）：

Webhook已创建（包含签名密钥）

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"secret": "string"
}

字段	类型	必填	描述
id	string	是	格式：uuid
url	string	是	格式：uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	是
description	string	是	最大长度：500
isActive	boolean	是	默认值：true
createdAt	string	是	格式：date-time
secret	string	是	签名密钥；仅在创建时返回

错误：

• 400请求无效，例如筛选表达式无效、流程没有模型、不支持的上传类型或缺少必填字段
• 401缺少、无效、已禁用或已过期的API密钥

获取单个出站Webhook

端点： GET /v1/tenant/{tenantId}/webhooks/{webhookId}

**身份验证：**租户范围API密钥 · read作用域

参数：

名称	类型	位置	必填	描述
tenantId	string	路径	是	格式：uuid
webhookId	string	路径	是	格式：uuid

响应（200）：

Webhook

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

字段	类型	必填	描述
id	string	是	格式：uuid
url	string	是	格式：uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	是
description	string	是	最大长度：500
isActive	boolean	是	默认值：true
createdAt	string	是	格式：date-time

错误：

• 401缺少、无效、已禁用或已过期的API密钥
• 404未找到资源

更新出站Webhook

端点： PUT /v1/tenant/{tenantId}/webhooks/{webhookId}

身份验证： 租户范围API密钥 · write范围

参数：

名称	类型	位置	必填	描述
tenantId	string	path	是	格式：uuid
webhookId	string	path	是	格式：uuid

请求正文：

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true
}

字段	类型	必填	描述
url	string	否	接收已签名POST投递的公开https端点
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	否	触发向此webhook投递的事件
description	string	否	可选描述 最大长度：500
isActive	boolean	否	webhook是否已启用

响应（200）：

webhook已更新

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

字段	类型	必填	描述
id	string	是	格式：uuid
url	string	是	格式：uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	是
description	string	是	最大长度：500
isActive	boolean	是	默认值：true
createdAt	string	是	格式：date-time

错误：

• 401 缺少、无效、已停用或已过期的API密钥
• 404 未找到资源

删除出站webhook

端点： DELETE /v1/tenant/{tenantId}/webhooks/{webhookId}

身份验证： 租户范围API密钥 · write范围

参数：

名称	类型	位置	必填	描述
tenantId	string	path	是	格式：uuid
webhookId	string	path	是	格式：uuid

响应（200）：

webhook已删除

{
	"deleted": true
}

字段	类型	必填	描述
deleted	boolean	是

错误：

• 401 缺少、无效、已停用或已过期的API密钥
• 404 未找到资源

触发向webhook的测试投递

端点： POST /v1/tenant/{tenantId}/webhooks/{webhookId}/test

身份验证： 租户范围API密钥 · write范围

参数：

名称	类型	位置	必填	描述
tenantId	string	path	是	格式：uuid
webhookId	string	path	是	格式：uuid

响应（200）：

测试投递已触发

{
	"message": "string"
}

字段	类型	必填	描述
message	string	是

错误：

• 401 缺少、无效、已停用或已过期的API密钥
• 404 未找到资源