API参考：Webhooks

当ProcessMind中发生事件时，出站Webhook会通知您自己的系统。每次发送都会以JSON POST请求发出，并使用您的Webhook密钥签名：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	路径	是	格式：uuid
webhookId	string	路径	是	格式：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	路径	是	格式：uuid
webhookId	string	路径	是	格式：uuid

响应（200）：

Webhook已删除

{
	"deleted": true
}

字段	类型	必填	说明
deleted	boolean	是

错误：

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

向Webhook触发测试投递

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

**身份验证：**环境级API密钥 · write权限范围

参数：

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

响应（200）：

已触发测试投递

{
	"message": "string"
}

字段	类型	必填	说明
message	string	是

错误：

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