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-Agentbase-Webhook-Signature), to the enterprise's internal alerting gateway via the configured Webhook.
Prerequisites
Client initialization and authentication:
Available only on the server side and Console side: requires the Server SDK
Client(setEndpoint,setProject,setKey; the API Key must have thewebhooks.readandwebhooks.writescopes) or the Console SDK (Console Session / short-lived JWT).Not available in the Client / Web SDK: the browser side has no permission to manage project-level Webhooks.
Network requirements for the callback endpoint: Use an HTTP/HTTPS URL reachable from the instance; create and update validate the URL format and domain. Literal loopback and private IPs are rejected by the current validator; verify DNS and outbound boundaries against deployment network policy. The receiver should promptly return
2xx.
Usage workflow
Initialize the client and the
Webhooksservice: load theAPPBASE_ENDPOINT,APPBASE_PROJECT_ID, and anAPPBASE_API_KEYwith thewebhooks.writescope.Create a Webhook (
webhooks.create): specify a unique identifierwebhookId, namename, callback URLurl, array of listened event patternsevents(up to 100 entries, e.g.,databases.*.tables.*.rows.*.create), enabled statusenabled: true, TLS certificate validationsecurity: true, and optional HTTP Basic Auth credentials (httpUser/httpPass).Save the signing key and verify signatures: Store
signatureKeythrough a controlled channel; do not log it. Compute HMAC-SHA1 over the configured URL afterrawurldecodeand the raw request body bytes, and compare it withX-Agentbase-Webhook-Signature.Routine inspection and key rotation (
list/get/update/updateSignature/delete): usegetto check the delivery failure countattemptsand recent error logslogs; periodically, or when a leak is suspected, callupdateSignatureto atomically rotate thesignatureKey.
Key parameters and returns
Complete Method List and Parameter Matrix
| SDK Method (Node / Java) | Python Method | Go Method | REST Endpoint | Required Parameters | Optional Parameters | Return Model |
|---|---|---|---|---|---|---|
create({ webhookId, url, name, events, ... }) | create(...) | Create(...) | POST /v1/webhooks | webhookId, url, name (≤128 characters), events (1–100 event strings) | enabled (default true), security (default false; set true to verify TLS certificates), httpUser, httpPass | Webhook |
list({ queries, total }) (both queries and total are optional) | list(...) | List(...) | GET /v1/webhooks | None | queries (pagination/filtering), total (default true) | WebhookList |
get({ webhookId }) | get(...) | Get(...) | GET /v1/webhooks/{webhookId} | webhookId | None | Webhook |
update({ webhookId, name, url, events, ... }) | update(...) | Update(...) | PUT /v1/webhooks/{webhookId} | webhookId、name、url、events | enabled (omission writes true and resets failures), security (omission writes false), httpUser and httpPass (omission writes an empty string to each) | Webhook |
updateSignature({ webhookId }) | update_signature(...) | UpdateSignature(...) | PATCH /v1/webhooks/{webhookId}/signature | webhookId | None | Webhook (including the new signatureKey) |
delete({ webhookId }) | delete(...) | Delete(...) | DELETE /v1/webhooks/{webhookId} | webhookId | None | Empty (204) |
Webhook Return model fields and callback request headers
| Category | Field / Header | Type | Description |
|---|---|---|---|
Return model Webhook | $id / name / url | string | Webhook ID, name, and target callback URL. |
Return model Webhook | events | string[] | List of subscribed platform event wildcards (e.g., ["databases.enterprise_biz_db.tables.customer_tickets.rows.*"]). |
Return model Webhook | security / enabled | boolean | Whether to verify certificates (true enforce certificate validity) and whether delivery is enabled. |
Return model Webhook | signatureKey | string | Platform-generated signing key, used to verify the callback request header X-Agentbase-Webhook-Signature. |
Return model Webhook | attempts / logs | integer / string | Number of consecutive delivery failures and the response diagnostic log of the most recent delivery failure. |
| Callback HTTP request header | X-Agentbase-Webhook-Id | string | ID of the Webhook that triggered this delivery. |
| Callback HTTP request header | X-Agentbase-Webhook-Events | string | List of event names matched in this delivery (comma-separated). |
| Callback HTTP request header | X-Agentbase-Webhook-Project-Id | string | ID of the owning project (e.g., enterprise-ai-hub-210). |
| Callback HTTP request header | X-Agentbase-Webhook-User-Id | string | User ID of the operator who triggered the event (empty when triggered by a server-side API Key). |
| Callback HTTP request header | X-Agentbase-Webhook-Signature | string | base64(hmac_sha1(rawurldecode(configuredUrl) + rawBody, signatureKey)) Signature value. |
Errors and boundaries
Event pattern validation failure (
400 general_argument_invalid):eventsEach string in the array must match a valid platform event namespace (e.g.,users.*,databases.*.tables.*.rows.*,buckets.*.files.*,functions.*), and a single Webhook can bind at most 100 event rules.URL validation failure (
400): Check the HTTP/HTTPS format and domain requirements. Domain validation does not replace DNS or outbound network policy.Delivery failures and consumer idempotency: The worker records failure for cURL errors or HTTP status codes of at least
400; a3xxis not considered failed solely because it is non-2xx. On reaching the consecutive-failure limit it disables the webhook and recordslogs; queue retry behavior depends on deployment configuration. Receivers should promptly return2xxand implement business-appropriate idempotency.
SDK Category Differences
| SDK category | Coverage | Authentication method | Typical scenarios |
|---|---|---|---|
| Server SDK (Node.js / Java / Python / Go) | Full CRUD and updateSignature | Project 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 updateSignature | Admin Console Session / short-lived JWT | Console 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.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
import { Client, Webhooks, AgentbaseException } from 'agentbase-node-sdk';
import { createHmac, timingSafeEqual } from 'node:crypto';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!)
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!);
{
const prepareRequest = client.prepareRequest.bind(client);
client.prepareRequest = (...args) => {
const request = prepareRequest(...args);
request.options.redirect = 'error';
return request;
};
}
const webhooks = new Webhooks(client);
try {
const hook = await webhooks.create({
webhookId: 'wh_billing_events',
url: 'https://example.com/hooks/agentbase',
name: '计费与工单事件回调',
events: ['databases.enterprise_biz_db.tables.customer_tickets.rows.*.create', 'databases.enterprise_biz_db.tables.customer_tickets.rows.*.update'],
enabled: true,
security: true,
});
// Store hook.signatureKey securely; never log it.
console.log('Webhook created:', hook.$id);
} catch (err) {
if (err instanceof AgentbaseException) {
console.error(`Webhook request failed [${err.code} ${err.type}]`);
}
throw err;
}
// configuredUrl must be the exact saved URL; rawBody must be the original request bytes.
export function verifyWebhookSignature(configuredUrl: string, rawBody: Buffer, signatureHeader: string, signatureKey: string): boolean {
const urlBytes = Buffer.from(configuredUrl, 'utf8');
const decoded: number[] = [];
for (let i = 0; i < urlBytes.length; i++) {
if (urlBytes[i] === 37 && i + 2 < urlBytes.length) {
const hex = urlBytes.subarray(i + 1, i + 3).toString('ascii');
if (/^[0-9a-f]{2}$/i.test(hex)) {
decoded.push(Number.parseInt(hex, 16));
i += 2;
continue;
}
}
decoded.push(urlBytes[i]);
}
const expected = Buffer.from(createHmac('sha1', signatureKey)
.update(Buffer.from(decoded)).update(rawBody).digest('base64'), 'ascii');
const received = Buffer.from(signatureHeader, 'utf8');
return expected.length === received.length && timingSafeEqual(expected, received);
}import io.agentbase.Client;
import io.agentbase.services.Webhooks;
import io.agentbase.exceptions.AgentbaseException;
import java.util.List;
Client client = new Client()
.setEndpoint(System.getenv("APPBASE_ENDPOINT"))
.setProject(System.getenv("APPBASE_PROJECT_ID"))
.setKey(System.getenv("APPBASE_API_KEY"));
client.setHttpClient(new okhttp3.OkHttpClient.Builder()
.followRedirects(false).followSslRedirects(false).build());
Webhooks webhooks = new Webhooks(client);
try {
var hook = webhooks.create("wh_billing_events", "https://example.com/hooks/agentbase",
"计费事件回调", List.of("databases.enterprise_biz_db.tables.customer_tickets.rows.*.create", "databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"),
true, true, null, null);
// Store hook.getSignatureKey() securely; never log it.
System.out.println("Webhook created: " + hook.getId());
} catch (AgentbaseException e) {
System.err.println("Webhook request failed: " + e.getCode() + " " + e.getType());
}The Python Server SDK 2.12.0 default transport may forward the project API key on redirects. Use the REST tab in this section.
package main
import (
"errors"
"net/http"
"fmt"
"os"
"agentbase-go-sdk/agentbase"
)
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint(os.Getenv("APPBASE_ENDPOINT")),
agentbase.WithProject(os.Getenv("APPBASE_PROJECT_ID")),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
return errors.New("refuse redirects")
}
webhooks := agentbase.NewWebhooks(cl)
hook, err := webhooks.Create("wh_billing_events", "https://example.com/hooks/agentbase",
"计费事件回调", []string{"databases.enterprise_biz_db.tables.customer_tickets.rows.*.create", "databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"},
webhooks.WithCreateEnabled(true), webhooks.WithCreateSecurity(true))
if err != nil {
fmt.Fprintln(os.Stderr, "Webhook request failed")
return
}
// Store hook.SignatureKey securely; never log it.
fmt.Println("Webhook created:", hook.Id)
}(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
umask 077
response_file=$(mktemp)
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/webhooks" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"webhookId":"wh_billing_events","name":"计费事件回调","url":"https://example.com/hooks/agentbase","events":["databases.enterprise_biz_db.tables.customer_tickets.rows.*.create"],"enabled":true,"security":true}' \
-o "$response_file"
# The response contains a signing key. Transfer it to secure storage and remove the temporary file.
)Example Guide
JavaScript / TypeScript full example: ../examples/javascript.md
Python full example: ../examples/python.md
Java full example: ../examples/java.md
Go full example: ../examples/go.md