事件回调 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 | 轮换签名密钥 |
端点详解
平台将 rawurldecode 后的配置 URL 字节与原始请求体字节拼接,使用 signatureKey 计算 HMAC-SHA1 并进行 Base64 编码,写入签名头。接收方应先验签;失败计数和日志可用于排障。
请求与响应
以下按端点给出完整规格:输入(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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.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.enterprise_biz_db.tables.customer_tickets.rows.*.create),否则创建/更新被拒。 |
enabled | body | boolean | 否 | — | 是否启用,默认 true。 |
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 认证。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"webhookId": "wh_billing_events",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": ["databases.enterprise_biz_db.tables.customer_tickets.rows.*.create", "databases.enterprise_biz_db.tables.customer_tickets.rows.*.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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}PUT /v1/webhooks/{webhookId}
整体更新 Webhook:name / url / events 必填。省略 enabled 会按 true 写回并重置失败次数,省略 security 会按 false 写回并关闭 TLS 校验,省略 httpUser 或 httpPass 会将对应字段写为空字符串。更新时应显式提供需要保留的配置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
webhookId | path | string | 是 | — | Webhook ID。 |
name | body | string | 是 | — | 名称,≤128 字符(必填)。 |
url | body | string | 是 | — | 回调 URL(必填)。 |
events | body | string[] | 是 | — | 订阅事件数组,最多 100 条(必填)。 |
enabled | body | boolean | 否 | 默认 true | 是否启用;为 true 时重置失败次数。 |
security | body | boolean | 否 | 默认 false | 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 | 连续失败次数。 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PUT "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase-v2",
"events": ["databases.enterprise_biz_db.tables.customer_tickets.rows.*.create"],
"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-09-14T03:00:00.000+00:00",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase-v2",
"events": [
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.create"
],
"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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.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* |