事件回调 API
项目事件回调(Webhook)的注册、管理与签名轮换:项目内事件发生时,平台向登记的 HTTP 端点推送。
服务与资源边界
事件回调(Webhooks)API 负责管理项目内的异步事件推送订阅:当项目内发生数据库行变更(如客服工单 customer_tickets 新建或更新)、存储文件上传、函数执行完成或用户状态变更等平台事件时,Webhook 投递队列向已注册的外部 HTTPS 端点发起携带 HMAC 签名头的 POST 回调。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1。 - 路径前缀
/webhooks;资源:webhook({webhookId})。
认证与权限
认证与请求头约定见 通用约定。
- scope:
webhooks.read(查询)、webhooks.write(创建/更新/删除/签名轮换);项目 API Key 即可访问。
端点总览
Webhooks 模块提供 6 个管理端点,覆盖项目级 Webhook 的分页查询、创建注册、详情读取、全量更新、删除注销以及签名密钥(signatureKey)在线轮换。
端点清单
| 方法 + 路径 | 用途 | ||
|---|---|---|---|
GET /webhooks / POST /webhooks | Webhook 列表/创建 | ||
| `GET | PUT | DELETE /webhooks/{webhookId}` | Webhook 读改删 |
PATCH /webhooks/{webhookId}/signature | 轮换签名密钥 |
端点详解
每次平台向目标 url 推送事件时,都会使用该 Webhook 的 signatureKey 对请求载荷计算 HMAC-SHA1/SHA256 签名并写入请求头,接收方服务应当先验签再处理业务;当连续投递失败时,平台自动累加 attempts 计数并将最近一次对端响应错误写入 logs 字段供排障检索。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
Webhooks
GET /v1/webhooks
列出项目内全部 Webhook:可用 Query 查询串过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | SDK Query 生成的查询串数组,最多 100 条、每条最长 4096 字符;可过滤属性:name、url、httpUser、security、events、enabled、logs、attempts。 |
total | query | boolean | 否 | 默认 true | 设为 false 时响应 total 恒为 0,跳过计数。 |
输出:返回 webhookList(total + webhooks[]),元素为 webhook:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
name | string | 名称(≤128 字符)。 |
url | string | 回调 URL。 |
events | string[] | 订阅事件数组(最多 100 条)。 |
security | boolean | 是否开启对端 TLS 证书校验。 |
httpUser | string | Basic 认证用户名(≤256 字符)。 |
httpPass | string | Basic 认证密码(≤256 字符)。 |
signatureKey | string | 签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。 |
enabled | boolean | 是否启用。 |
logs | string | 最近一次投递失败的错误日志。 |
attempts | integer | 连续失败次数。 |
调用示例:
curl "https://<your-endpoint>/v1/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"webhooks": [
{
"$id": "wh_billing_events",
"$createdAt": "2026-08-20T10:00:00.000+00:00",
"$updatedAt": "2026-08-20T10:00:00.000+00:00",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": [
"databases.tables.update",
"databases.collections.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}
]
}POST /v1/webhooks
创建 Webhook:注册一个接收平台事件的回调 URL;创建响应包含签名密钥,用于接收方校验回调来源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
webhookId | body | string | 是 | — | Webhook ID:自定义或 ID.unique();允许 a-z A-Z 0-9 点、连字符、下划线,不得以特殊字符开头,最长 36 字符。 |
url | body | string | 是 | — | 回调 URL。 |
name | body | string | 是 | — | 名称,≤128 字符。 |
events | body | string[] | 是 | — | 订阅事件数组,最多 100 条;事件名必须在平台事件枚举内(如 databases.tables.update),否则创建/更新被拒。 |
enabled | body | boolean | 否 | — | 是否启用,默认 false。 |
security | body | boolean | 否 | — | 对回调目标 TLS 证书的校验开关,默认 false。 |
httpUser | body | string | 否 | — | Basic 认证用户名,≤256 字符。 |
httpPass | body | string | 否 | — | Basic 认证密码,≤256 字符。 |
输出:返回 201 + webhook(含 signatureKey):
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
name | string | 名称(≤128 字符)。 |
url | string | 回调 URL。 |
events | string[] | 订阅事件数组(最多 100 条)。 |
security | boolean | 是否开启对端 TLS 证书校验。 |
httpUser | string | Basic 认证用户名(≤256 字符)。 |
httpPass | string | Basic 认证密码(≤256 字符)。 |
signatureKey | string | 签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。 |
enabled | boolean | 是否启用。 |
logs | string | 最近一次投递失败的错误日志。 |
attempts | integer | 连续失败次数。 |
- 回调以签名头投递;接收方用
signatureKey校验来源。回调失败按平台重试策略处理,本 API 不管理重试队列。 httpUser/httpPass仅支持 Basic 认证。
调用示例:
curl -X POST "https://<your-endpoint>/v1/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"webhookId": "wh_billing_events",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": ["databases.tables.update", "databases.collections.update"],
"enabled": true,
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass"
}'响应示例:
{
"$id": "wh_billing_events",
"$createdAt": "2026-08-20T10:00:00.000+00:00",
"$updatedAt": "2026-08-20T10:00:00.000+00:00",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": [
"databases.tables.update",
"databases.collections.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}GET /v1/webhooks/{webhookId}
按 ID 读取单个 Webhook 配置与最近投递状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
webhookId | path | string | 是 | — | Webhook ID。 |
输出:返回 webhook:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
name | string | 名称(≤128 字符)。 |
url | string | 回调 URL。 |
events | string[] | 订阅事件数组(最多 100 条)。 |
security | boolean | 是否开启对端 TLS 证书校验。 |
httpUser | string | Basic 认证用户名(≤256 字符)。 |
httpPass | string | Basic 认证密码(≤256 字符)。 |
signatureKey | string | 签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。 |
enabled | boolean | 是否启用。 |
logs | string | 最近一次投递失败的错误日志。 |
attempts | integer | 连续失败次数。 |
调用示例:
curl "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "wh_billing_events",
"$createdAt": "2026-08-20T10:00:00.000+00:00",
"$updatedAt": "2026-08-20T10:00:00.000+00:00",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": [
"databases.tables.update",
"databases.collections.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}PUT /v1/webhooks/{webhookId}
整体更新 Webhook:name / url / events 必填,其余可选。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
webhookId | path | string | 是 | — | Webhook ID。 |
name | body | string | 是 | — | 名称,≤128 字符(必填)。 |
url | body | string | 是 | — | 回调 URL(必填)。 |
events | body | string[] | 是 | — | 订阅事件数组,最多 100 条(必填)。 |
enabled | body | boolean | 否 | — | 是否启用。 |
security | body | boolean | 否 | — | TLS 证书校验开关。 |
httpUser | body | string | 否 | — | Basic 认证用户名,≤256 字符。 |
httpPass | body | string | 否 | — | Basic 认证密码,≤256 字符。 |
输出:返回更新后的 webhook:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
name | string | 名称(≤128 字符)。 |
url | string | 回调 URL。 |
events | string[] | 订阅事件数组(最多 100 条)。 |
security | boolean | 是否开启对端 TLS 证书校验。 |
httpUser | string | Basic 认证用户名(≤256 字符)。 |
httpPass | string | Basic 认证密码(≤256 字符)。 |
signatureKey | string | 签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。 |
enabled | boolean | 是否启用。 |
logs | string | 最近一次投递失败的错误日志。 |
attempts | integer | 连续失败次数。 |
调用示例:
curl -X PUT "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase-v2",
"events": ["databases.tables.update"],
"enabled": true
}'响应示例:
{
"$id": "wh_billing_events",
"$createdAt": "2026-08-20T10:00:00.000+00:00",
"$updatedAt": "2026-09-14T03:00:00.000+00:00",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase-v2",
"events": [
"databases.tables.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}DELETE /v1/webhooks/{webhookId}
删除 Webhook:删除后不再接收任何项目事件。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
webhookId | path | string | 是 | — | Webhook ID。 |
输出:204 No Content,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:204 No Content:无响应体(已删除)。
PATCH /v1/webhooks/{webhookId}/signature
轮换 Webhook 签名密钥:旧密钥立即失效,响应返回新密钥;怀疑泄露或定期轮换时使用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
webhookId | path | string | 是 | — | Webhook ID。 |
输出:返回更新后的 webhook(signatureKey 为新值):
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
name | string | 名称(≤128 字符)。 |
url | string | 回调 URL。 |
events | string[] | 订阅事件数组(最多 100 条)。 |
security | boolean | 是否开启对端 TLS 证书校验。 |
httpUser | string | Basic 认证用户名(≤256 字符)。 |
httpPass | string | Basic 认证密码(≤256 字符)。 |
signatureKey | string | 签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。 |
enabled | boolean | 是否启用。 |
logs | string | 最近一次投递失败的错误日志。 |
attempts | integer | 连续失败次数。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/webhooks/wh_billing_events/signature" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "wh_billing_events",
"$createdAt": "2026-08-20T10:00:00.000+00:00",
"$updatedAt": "2026-09-14T03:10:00.000+00:00",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": [
"databases.tables.update",
"databases.collections.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "f7c2e91b04da6f3c8e1b2a9d",
"enabled": true,
"logs": "",
"attempts": 0
}错误与边界
- Webhook 事件名不在平台事件枚举内:创建/更新被拒;
events超 100 条被拒。 httpUser/httpPass仅支持 Basic 认证;回调失败按平台重试策略处理,不在本 API 内管理重试队列。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Webhooks.list / create / get / update / delete / updateSignature | /webhooks* |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0 同名 service。 - 语义深度参考:
skills/ob-agentbase/references/environment-context.md。