Docs
Contents

Event Callbacks

Overview and use cases

Webhooks The service pushes domain events within a project (such as database table/row create, update, and delete operations, storage bucket file uploads, user registration and session login, team changes, function deployment and execution, etc.) in real time to the callback endpoint of an external business system via asynchronous HTTP POST requests. It is independent of the platform's internal Function event triggers and is suitable for integrating with enterprise internal support ticket centers, audit archival services, CRM/ERP systems, or billing reconciliation pipelines.

In enterprise intelligent customer service and knowledge platforms (such as the demo project enterprise-ai-hub-210), when a new support ticket is created in the enterprise_biz_db.customer_tickets table (e.g., TK-20261022-001) or its status is updated, the platform can deliver the event payload, along with the HMAC signature header (X-Appwrite-Webhook-Signature), to the enterprise's internal alerting gateway via the configured Webhook.

Prerequisites

Usage workflow

  1. Initialize the client and the Webhooks service: load the APPBASE_ENDPOINT, APPBASE_PROJECT_ID, and an APPBASE_API_KEY with the webhooks.write scope.

  2. Create a Webhook (webhooks.create): specify a unique identifier webhookId, name name, callback URL url, array of listened event patterns events (up to 100 entries, e.g., databases.*.tables.*.rows.create), enabled status enabled: true, TLS certificate validation security: true, and optional HTTP Basic Auth credentials (httpUser / httpPass).

  3. Save the signing key and verify signatures: read the signatureKey from the creation or detail response, and in the receiving HTTP service compare the HMAC-SHA1 signature of the raw request body combined with the X-Appwrite-Webhook-Signature request header to reject forged requests.

  4. Routine inspection and key rotation (list / get / update / updateSignature / delete): use get to check the delivery failure count attempts and recent error logs logs; periodically, or when a leak is suspected, call updateSignature to atomically rotate the signatureKey.

Key parameters and returns

Complete Method List and Parameter Matrix

SDK Method (Node / Java)Python MethodGo MethodREST EndpointRequired ParametersOptional ParametersReturn Model
create({ webhookId, url, name, events, ... })create(...)Create(...)POST /v1/webhookswebhookId, url, name (≤128 characters), events (1–100 event strings)enabled (default true), security (default true, validates the remote TLS certificate), httpUser, httpPassWebhook
list({ queries, total }) (both queries and total are optional)list(...)List(...)GET /v1/webhooksNonequeries (pagination/filtering), total (default true)WebhookList
get({ webhookId })get(...)Get(...)GET /v1/webhooks/{webhookId}webhookIdNoneWebhook
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}/signaturewebhookIdNoneWebhook (including the new signatureKey)
delete({ webhookId })delete(...)Delete(...)DELETE /v1/webhooks/{webhookId}webhookIdNoneEmpty (204)

Webhook Return model fields and callback request headers

CategoryField / HeaderTypeDescription
Return model Webhook$id / name / urlstringWebhook ID, name, and target callback URL.
Return model Webhookeventsstring[]List of subscribed platform event wildcards (e.g., ["databases.enterprise_biz_db.tables.customer_tickets.rows.*"]).
Return model Webhooksecurity / enabledbooleanWhether to verify certificates (true enforce certificate validity) and whether delivery is enabled.
Return model WebhooksignatureKeystringPlatform-generated signing key, used to verify the callback request header X-Appwrite-Webhook-Signature.
Return model Webhookattempts / logsinteger / stringNumber of consecutive delivery failures and the response diagnostic log of the most recent delivery failure.
Callback HTTP request headerX-Appwrite-Webhook-IdstringID of the Webhook that triggered this delivery.
Callback HTTP request headerX-Appwrite-Webhook-EventsstringList of event names matched in this delivery (comma-separated).
Callback HTTP request headerX-Appwrite-Webhook-Project-IdstringID of the owning project (e.g., enterprise-ai-hub-210).
Callback HTTP request headerX-Appwrite-Webhook-User-IdstringUser ID of the operator who triggered the event (empty when triggered by a server-side API Key).
Callback HTTP request headerX-Appwrite-Webhook-Signaturestringbase64(hmac_sha1(url + rawBody, signatureKey)) Signature value.

Errors and boundaries

SDK Category Differences

SDK categoryCoverageAuthentication methodTypical scenarios
Server SDK (Node.js / Java / Python / Go)Full CRUD and updateSignatureProject API Key (webhooks.read / webhooks.write)Backend services automatically register callbacks, periodically rotate signing keys, and inspect failing Webhooks
Console SDK (Node.js / Java / Python / Go)Full CRUD and updateSignatureAdmin Console Session / short-lived JWTConsole Webhook management pages and operations scripts
Client / Web SDK (Web)None Webhooks Service—Browsers cannot manage Webhooks

Examples by language

Credentials: Project API Key (webhooks.* scope) or Console Session; not available in browsers, no web tab.

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. Create support ticket and billing event callbacks
    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, // Enforce validation of the target HTTPS certificate and verify the signature with the returned signatureKey
    });
    console.log('Webhook 创建成功, signatureKey:', hook.signatureKey);

    // 2. List and rotate signature keys (REST equivalent 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;
}

// Appendix: utility function for verifying X-Appwrite-Webhook-Signature on the receiver side
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));
}

Example Guide