事件回调
这是什么 / 何时用
Webhooks 把项目事件推送到你的 HTTP 端点,用于服务端集成(与 Function 的事件触发是两条链路)。事件发生时平台向登记的 url 推送;security: true 时带签名头。
前置
- 仅服务端与 Console 侧可用:项目 API Key(
webhooks.read/webhooks.writescope)或 Console Session;浏览器不可用。 - 回调端点必须公网可达且回应快速。
使用骨架
webhooks.create({ webhookId, url, name, events, enabled, security, httpUser, httpPass }) 创建;list / get / update / delete 维护;updateSignature 轮换签名密钥。
关键参数与返回
events为事件名字符串数组(平台事件枚举内,不超 100 条)。- 返回的 webhook 对象含
signatureKey(安全校验用)与enabled。
错误与边界
- 事件名不在平台事件枚举内:创建/更新被拒。
httpUser/httpPass仅支持 Basic 认证;签名校验失败时按不可信处理。
各语言调用示例
凭据:项目 API Key(webhooks.* scope)或 Console Session;浏览器不可用,无 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Webhooks } from 'agentbase-node-sdk';
const webhooks = new Webhooks(client);
await webhooks.create({
webhookId: 'wh_billing_events',
url: 'https://example.com/hooks/agentbase',
name: '计费事件回调',
events: ['databases.tables.update', 'databases.collections.update'],
enabled: true,
security: true // 平台推送带签名头,用返回的 signatureKey 校验来源
});
const list = await webhooks.list(); // get / update / delete 维护同一个 webhook
// 轮换签名密钥:webhooks.updateSignature(...)(REST 对应 PATCH /webhooks/{webhookId}/signature)import io.agentbase.services.Webhooks;
Webhooks webhooks = new Webhooks(client); // client 初始化见 server-sdk/java.md
webhooks.create("wh_billing_events", "https://example.com/hooks/agentbase",
"计费事件回调", List.of("databases.tables.update", "databases.collections.update"),
true, true, null, null); // enabled / security;可选 httpUser / httpPass
webhooks.list(null, true); // get / update / delete 维护同一个 webhook
webhooks.updateSignature("wh_billing_events"); // 轮换签名密钥(REST 对应 PATCH /webhooks/{webhookId}/signature)from agentbase.services.webhooks import Webhooks
webhooks = Webhooks(client) # 方法面与 Node SDK 同构
webhooks.create(
webhook_id='wh_billing_events', url='https://example.com/hooks/agentbase',
name='计费事件回调', events=['databases.tables.update', 'databases.collections.update'],
enabled=True, security=True)
# list / get / update / delete 维护;轮换签名密钥 update_signature(REST 对应 PATCH /webhooks/{webhookId}/signature)webhooks := agentbase.NewWebhooks(cl) // facade 构造器;cl 为已装载 API Key 的 Client
webhooks.Create("wh_billing_events", "https://example.com/hooks/agentbase",
"计费事件回调", []string{"databases.tables.update", "databases.collections.update"},
webhooks.WithCreateEnabled(true),
webhooks.WithCreateSecurity(true)) // 平台推送带签名头,用返回的 signatureKey 校验来源
webhooks.List() // Get / Update / Delete 维护同一个 webhook
webhooks.UpdateSignature("wh_billing_events") // 轮换签名密钥(REST 对应 PATCH /webhooks/{webhookId}/signature)curl -sS -X POST "$APPBASE_ENDPOINT/v1/webhooks" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"webhookId":"wh_billing_events","name":"计费事件回调","url":"https://example.com/hooks/agentbase","events":["databases.tables.update"],"enabled":true,"security":true,"httpUser":"hook-user","httpPass":"hook-pass"}'
# 列表/单条:GET /v1/webhooks、GET /v1/webhooks/{webhookId};改:PUT /v1/webhooks/{webhookId};删:DELETE /v1/webhooks/{webhookId}
# 轮换签名密钥:PATCH /v1/webhooks/{webhookId}/signature;回调以签名头投递,失败按平台重试策略处理SDK 类别差异
- Server SDK(server-sdk/nodejs.md):全量。
- 客户端 SDK(client-sdk/web.md):无 Webhooks。
- Console SDK(console-sdk/nodejs.md):全量。
事实源
skills/ob-agentbase/references/server-sdks/java.md(模块总览)skills/ob-agentbase/references/server-sdks/nodejs.md(模块表)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/services/webhooks.ts方法面)