agentbase-docs

事件回调 API

项目事件回调(Webhook)的注册、管理与签名轮换:项目内事件发生时,平台向登记的 HTTP 端点推送。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。

端点清单

方法 + 路径用途
GET /webhooks / POST /webhooksWebhook 列表/创建
`GETPUTDELETE /webhooks/{webhookId}`Webhook 读改删
PATCH /webhooks/{webhookId}/signature轮换签名密钥

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

Webhooks

GET /v1/webhooks

列出项目内全部 Webhook:可用 Query 查询串过滤。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []SDK Query 生成的查询串数组,最多 100 条、每条最长 4096 字符;可过滤属性:name、url、httpUser、security、events、enabled、logs、attempts。
totalqueryboolean否默认 true设为 false 时响应 total 恒为 0,跳过计数。

输出:返回 webhookList(total + webhooks[]),元素为 webhook:

字段类型说明
$idstringWebhook ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
namestring名称(≤128 字符)。
urlstring回调 URL。
eventsstring[]订阅事件数组(最多 100 条)。
securityboolean是否开启对端 TLS 证书校验。
httpUserstringBasic 认证用户名(≤256 字符)。
httpPassstringBasic 认证密码(≤256 字符)。
signatureKeystring签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。
enabledboolean是否启用。
logsstring最近一次投递失败的错误日志。
attemptsinteger连续失败次数。

调用示例:

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;创建响应包含签名密钥,用于接收方校验回调来源。

输入:

参数位置类型必填默认/枚举说明
webhookIdbodystring是—Webhook ID:自定义或 ID.unique();允许 a-z A-Z 0-9 点、连字符、下划线,不得以特殊字符开头,最长 36 字符。
urlbodystring是—回调 URL。
namebodystring是—名称,≤128 字符。
eventsbodystring[]是—订阅事件数组,最多 100 条;事件名必须在平台事件枚举内(如 databases.tables.update),否则创建/更新被拒。
enabledbodyboolean否—是否启用,默认 false。
securitybodyboolean否—对回调目标 TLS 证书的校验开关,默认 false。
httpUserbodystring否—Basic 认证用户名,≤256 字符。
httpPassbodystring否—Basic 认证密码,≤256 字符。

输出:返回 201 + webhook(含 signatureKey):

字段类型说明
$idstringWebhook ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
namestring名称(≤128 字符)。
urlstring回调 URL。
eventsstring[]订阅事件数组(最多 100 条)。
securityboolean是否开启对端 TLS 证书校验。
httpUserstringBasic 认证用户名(≤256 字符)。
httpPassstringBasic 认证密码(≤256 字符)。
signatureKeystring签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。
enabledboolean是否启用。
logsstring最近一次投递失败的错误日志。
attemptsinteger连续失败次数。

调用示例:

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 配置与最近投递状态。

输入:

参数位置类型必填默认/枚举说明
webhookIdpathstring是—Webhook ID。

输出:返回 webhook:

字段类型说明
$idstringWebhook ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
namestring名称(≤128 字符)。
urlstring回调 URL。
eventsstring[]订阅事件数组(最多 100 条)。
securityboolean是否开启对端 TLS 证书校验。
httpUserstringBasic 认证用户名(≤256 字符)。
httpPassstringBasic 认证密码(≤256 字符)。
signatureKeystring签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。
enabledboolean是否启用。
logsstring最近一次投递失败的错误日志。
attemptsinteger连续失败次数。

调用示例:

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 必填,其余可选。

输入:

参数位置类型必填默认/枚举说明
webhookIdpathstring是—Webhook ID。
namebodystring是—名称,≤128 字符(必填)。
urlbodystring是—回调 URL(必填)。
eventsbodystring[]是—订阅事件数组,最多 100 条(必填)。
enabledbodyboolean否—是否启用。
securitybodyboolean否—TLS 证书校验开关。
httpUserbodystring否—Basic 认证用户名,≤256 字符。
httpPassbodystring否—Basic 认证密码,≤256 字符。

输出:返回更新后的 webhook:

字段类型说明
$idstringWebhook ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
namestring名称(≤128 字符)。
urlstring回调 URL。
eventsstring[]订阅事件数组(最多 100 条)。
securityboolean是否开启对端 TLS 证书校验。
httpUserstringBasic 认证用户名(≤256 字符)。
httpPassstringBasic 认证密码(≤256 字符)。
signatureKeystring签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。
enabledboolean是否启用。
logsstring最近一次投递失败的错误日志。
attemptsinteger连续失败次数。

调用示例:

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:删除后不再接收任何项目事件。

输入:

参数位置类型必填默认/枚举说明
webhookIdpathstring是—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 签名密钥:旧密钥立即失效,响应返回新密钥;怀疑泄露或定期轮换时使用。

输入:

参数位置类型必填默认/枚举说明
webhookIdpathstring是—Webhook ID。

输出:返回更新后的 webhook(signatureKey 为新值):

字段类型说明
$idstringWebhook ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
namestring名称(≤128 字符)。
urlstring回调 URL。
eventsstring[]订阅事件数组(最多 100 条)。
securityboolean是否开启对端 TLS 证书校验。
httpUserstringBasic 认证用户名(≤256 字符)。
httpPassstringBasic 认证密码(≤256 字符)。
signatureKeystring签名密钥:平台用它对回调签名,接收方据此校验请求来源;轮换接口会返回新值。
enabledboolean是否启用。
logsstring最近一次投递失败的错误日志。
attemptsinteger连续失败次数。

调用示例:

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
}

错误与边界

与 Server SDK 的对应

service.method端点
Webhooks.list / create / get / update / delete / updateSignature/webhooks*

事实源