AgentbaseDocs
文档目录

事件回调

这是什么 / 何时用

Webhooks 服务用于将项目内的领域事件(如数据库表/行增删改、存储桶文件上传、用户注册与会话登录、团队变更、函数部署执行等)以异步 HTTP POST 请求实时推送到外部业务系统的回调端点。它与平台内部的 Function 事件触发器相互独立,适合对接企业内部工单中心、审计归档服务、CRM/ERP 系统或计费对账流水线。

在企业智能客服与知识中台(如演示项目 enterprise-ai-hub-210)中,当 enterprise_biz_db.customer_tickets 表产生新工单(如 TK-20261022-001)或状态更新时,平台可通过配置的 Webhook 将事件载荷连同 HMAC 签名头(X-Appwrite-Webhook-Signature)投递给企业内部告警网关。

前置

使用骨架

关键参数与返回

方法全集与参数矩阵

SDK 方法(Node / Java)Python 方法Go 方法REST 端点必填参数可选参数返回模型
create({ webhookId, url, name, events, ... })create(...)Create(...)POST /v1/webhookswebhookId、url、name(≤128 字符)、events(1–100 条事件串)enabled(默认 true)、security(默认 true,校验远端 TLS 证书)、httpUser、httpPassWebhook
list({ queries?, total? })list(...)List(...)GET /v1/webhooks无queries(分页/过滤)、total(默认 true)WebhookList
get({ webhookId })get(...)Get(...)GET /v1/webhooks/{webhookId}webhookId无Webhook
update({ webhookId, name, url, events, ... })update(...)Update(...)PUT /v1/webhooks/{webhookId}webhookId、name、url、eventsenabled、security、httpUser、httpPassWebhook
updateSignature({ webhookId })update_signature(...)UpdateSignature(...)PATCH /v1/webhooks/{webhookId}/signaturewebhookId无Webhook(含新 signatureKey)
delete({ webhookId })delete(...)Delete(...)DELETE /v1/webhooks/{webhookId}webhookId无空(204)

Webhook 返回模型字段与回调请求头

类别字段 / 请求头类型说明
返回模型 Webhook$id / name / urlstringWebhook ID、名称与目标回调 URL。
返回模型 Webhookeventsstring[]订阅的平台事件通配符列表(如 ["databases.enterprise_biz_db.tables.customer_tickets.rows.*"])。
返回模型 Webhooksecurity / enabledboolean是否校验证书(true 强制校验证书有效性)与是否启用投递。
返回模型 WebhooksignatureKeystring平台生成的签名密钥,用于校验回调请求头 X-Appwrite-Webhook-Signature。
返回模型 Webhookattempts / logsinteger / string连续投递失败次数与最近一次投递失败的响应诊断日志。
回调 HTTP 请求头X-Appwrite-Webhook-Idstring触发本次投递的 Webhook ID。
回调 HTTP 请求头X-Appwrite-Webhook-Eventsstring本次匹配的事件名称列表(逗号分隔)。
回调 HTTP 请求头X-Appwrite-Webhook-Project-Idstring所属项目 ID(如 enterprise-ai-hub-210)。
回调 HTTP 请求头X-Appwrite-Webhook-User-Idstring触发事件的操纵者用户 ID(服务端 API Key 触发时为空)。
回调 HTTP 请求头X-Appwrite-Webhook-Signaturestringbase64(hmac_sha1(url + rawBody, signatureKey)) 签名值。

错误与边界

SDK 类别差异

SDK 类别支持范围鉴权方式典型场景
Server SDK(Node.js / Java / Python / Go)全量 CRUD 与 updateSignature项目 API Key(webhooks.read / webhooks.write)后端服务自动注册回调、定期轮换签名密钥、巡检失败 Webhook
Console SDK(Node.js / Java / Python / Go)全量 CRUD 与 updateSignature管理面 Session / 短期 JWT控制台 Webhook 管理页面与运维脚本
Client / Web SDK(Web)**无 Webhooks 服务**—浏览器不可管理 Webhook

各语言调用示例

凭据:项目 API Key(webhooks.* scope)或 Console Session;浏览器不可用,无 Web 页签。

import { Client, Webhooks, AgentbaseException } from 'agentbase-node-sdk';
import { createHmac, timingSafeEqual } from 'node:crypto';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
    .setProject(process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210')
    .setKey(process.env.APPBASE_API_KEY!);

const webhooks = new Webhooks(client);

try {
    // 1. 创建工单与计费事件回调
    const hook = 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, // 强制校验目标 HTTPS 证书并用返回的 signatureKey 校验签名
    });
    console.log('Webhook 创建成功, signatureKey:', hook.signatureKey);

    // 2. 列出并轮换签名密钥(REST 对应 PATCH /v1/webhooks/{webhookId}/signature)
    const list = await webhooks.list();
    const rotated = await webhooks.updateSignature({ webhookId: 'wh_billing_events' });
    console.log('当前 Webhook 总数:', list.total, '轮换后新密钥长度:', rotated.signatureKey.length);
} catch (err) {
    if (err instanceof AgentbaseException) {
        console.error(`Webhooks 调用失败 [${err.code} ${err.type}]: ${err.message}`);
    }
    throw err;
}

// 附:接收端校验 X-Appwrite-Webhook-Signature 的工具函数
export function verifyWebhookSignature(webhookUrl: string, rawBody: string, signatureHeader: string, signatureKey: string): boolean {
    const expected = createHmac('sha1', signatureKey).update(webhookUrl + rawBody).digest('base64');
    return expected.length === signatureHeader.length &&
        timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

示例指引

事实源