Event Callback API
Registration, management, and signature rotation for project event callbacks (Webhooks): when events occur within a project, the platform pushes them to registered HTTP endpoints.
Service and resource boundaries
The Event Callbacks (Webhooks) API manages asynchronous event push subscriptions within a project: when platform events occur within a project — such as creation or update of a database row (like a support ticket customer_tickets), storage file uploads, function execution completion, or user status changes — the Webhook delivery queue sends a POST callback with an HMAC signature header to the registered external HTTPS endpoint.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1。Path prefix
/webhooks; resource:webhook({webhookId}).
Authentication and Permissions
See general conventions for authentication and request header conventions.
Scopes:
webhooks.read(read),webhooks.write(create/update/delete/signature rotation); accessible with a project API Key.
Endpoint overview
The Webhooks module provides 6 management endpoints, covering paginated queries, creation and registration, detail retrieval, full updates, deletion and deregistration, and online rotation of signature keys (signatureKey) for project-level Webhooks.
Endpoint List
| Method + path | Purpose |
|---|---|
GET /webhooks / POST /webhooks | Webhook list/create |
GET|PUT|DELETE /webhooks/{webhookId} | Webhook read/update/delete |
PATCH /webhooks/{webhookId}/signature | Rotate signature key |
Endpoint details
The platform concatenates the configured URL bytes after rawurldecode with the raw request body bytes, computes HMAC-SHA1 using signatureKey, and Base64-encodes it into the signature header. Verify it before processing; failure counts and logs aid diagnosis.
Requests and Responses
Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), call examples (copyable curl) and response examples. Endpoints marked with "generalized schema any" return the JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for specific fields.
Webhooks
GET /v1/webhooks
List all Webhooks in the project: query strings can be used for filtering.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | SDK Query Generated array of query strings, up to 100 items, each at most 4096 characters; filterable attributes: name, url, httpUser, security, events, enabled, logs, attempts. |
total | query | boolean | No | Default true | When set to false, the response total is always 0, skipping counting. |
Output: Returns webhookList (total + webhooks[]), with elements of webhook:
| Field | Type | Description |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | Creation time (ISO 8601). |
$updatedAt | string | Last update time (ISO 8601). |
name | string | Name (≤128 characters). |
url | string | Callback URL. |
events | string[] | Array of subscribed events (up to 100 items). |
security | boolean | Whether to enable peer TLS certificate verification. |
httpUser | string | Basic authentication username (≤256 characters). |
httpPass | string | Basic authentication password (≤256 characters). |
signatureKey | string | Signing secret: the platform uses it to sign callbacks, and the receiver uses it to verify the request origin; the rotation endpoint returns a new value. |
enabled | boolean | Whether it is enabled. |
logs | string | Error log of the most recent delivery failure. |
attempts | integer | Number of consecutive failures. |
Call example:
curl "https://<your-endpoint>/v1/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}
]
}POST /v1/webhooks
Create a Webhook: register a callback URL to receive platform events; the creation response includes a signing secret for the receiver to verify the callback origin.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
webhookId | body | string | Yes | — | Webhook ID: custom or ID.unique(); allows a-z A-Z 0-9 dots, hyphens, underscores, must not start with a special character, up to 36 characters. |
url | body | string | Yes | — | Callback URL. |
name | body | string | Yes | — | Name, ≤128 characters. |
events | body | string[] | Yes | — | Array of subscribed events, up to 100 items; event names must be within the platform event enumeration (e.g. databases.enterprise_biz_db.tables.customer_tickets.rows.*.create), otherwise creation/update is rejected. |
enabled | body | boolean | No | — | Whether to enable, default true. |
security | body | boolean | No | — | Toggle for TLS certificate verification of the callback target, default false. |
httpUser | body | string | No | — | Basic authentication username, ≤256 characters. |
httpPass | body | string | No | — | Basic authentication password, ≤256 characters. |
Output: Returns 201 + webhook (including signatureKey):
| Field | Type | Description |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | Creation time (ISO 8601). |
$updatedAt | string | Last update time (ISO 8601). |
name | string | Name (≤128 characters). |
url | string | Callback URL. |
events | string[] | Array of subscribed events (up to 100 items). |
security | boolean | Whether to enable peer TLS certificate verification. |
httpUser | string | Basic authentication username (≤256 characters). |
httpPass | string | Basic authentication password (≤256 characters). |
signatureKey | string | Signing secret: the platform uses it to sign callbacks, and the receiver uses it to verify the request origin; the rotation endpoint returns a new value. |
enabled | boolean | Whether it is enabled. |
logs | string | Error log of the most recent delivery failure. |
attempts | integer | Number of consecutive failures. |
Callbacks are delivered with a signature header; the receiver uses
signatureKeyto verify the origin. Callback failures are handled per the platform retry policy; this API does not manage a retry queue.httpUser/httpPassonly support Basic authentication.
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"webhookId": "wh_billing_events",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": ["databases.enterprise_biz_db.tables.customer_tickets.rows.*.create", "databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"],
"enabled": true,
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass"
}'
)Response example:
{
"$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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}GET /v1/webhooks/{webhookId}
Read a single Webhook's configuration and most recent delivery status by ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
webhookId | path | string | Yes | — | Webhook ID. |
Output: Returns webhook:
| Field | Type | Description |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | Creation time (ISO 8601). |
$updatedAt | string | Last update time (ISO 8601). |
name | string | Name (≤128 characters). |
url | string | Callback URL. |
events | string[] | Array of subscribed events (up to 100 items). |
security | boolean | Whether to enable peer TLS certificate verification. |
httpUser | string | Basic authentication username (≤256 characters). |
httpPass | string | Basic authentication password (≤256 characters). |
signatureKey | string | Signing secret: the platform uses it to sign callbacks, and the receiver uses it to verify the request origin; the rotation endpoint returns a new value. |
enabled | boolean | Whether it is enabled. |
logs | string | Error log of the most recent delivery failure. |
attempts | integer | Number of consecutive failures. |
Call example:
curl "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}PUT /v1/webhooks/{webhookId}
Full update of a Webhook: name / url / events are required. Omitting enabled writes true and resets the failure count; omitting security writes false and disables TLS verification; omitting httpUser or httpPass writes an empty string to that field. Explicitly provide the configuration you need to retain.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
webhookId | path | string | Yes | — | Webhook ID. |
name | body | string | Yes | — | Name, ≤128 characters (required). |
url | body | string | Yes | — | Callback URL (required). |
events | body | string[] | Yes | — | Array of subscribed events, up to 100 items (required). |
enabled | body | boolean | No | Default true | Whether to enable; true resets the failure count. |
security | body | boolean | No | Default false | TLS certificate verification toggle; omission disables verification. |
httpUser | body | string | No | Default empty string | Basic authentication username, ≤256 characters; omission clears it. |
httpPass | body | string | No | Default empty string | Basic authentication password, ≤256 characters; omission clears it. |
Output: Returns the updated webhook:
| Field | Type | Description |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | Creation time (ISO 8601). |
$updatedAt | string | Last update time (ISO 8601). |
name | string | Name (≤128 characters). |
url | string | Callback URL. |
events | string[] | Array of subscribed events (up to 100 items). |
security | boolean | Whether to enable peer TLS certificate verification. |
httpUser | string | Basic authentication username (≤256 characters). |
httpPass | string | Basic authentication password (≤256 characters). |
signatureKey | string | Signing secret: the platform uses it to sign callbacks, and the receiver uses it to verify the request origin; the rotation endpoint returns a new value. |
enabled | boolean | Whether it is enabled. |
logs | string | Error log of the most recent delivery failure. |
attempts | integer | Number of consecutive failures. |
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PUT "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase-v2",
"events": ["databases.enterprise_biz_db.tables.customer_tickets.rows.*.create"],
"enabled": true,
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass"
}'
)Response example:
{
"$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.enterprise_biz_db.tables.customer_tickets.rows.*.create"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "ad3d581ca230e2b7059c545e5a",
"enabled": true,
"logs": "",
"attempts": 0
}DELETE /v1/webhooks/{webhookId}
Delete a Webhook: after deletion, no project events are received anymore.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
webhookId | path | string | Yes | — | Webhook ID. |
Output: 204 No Content, no response body.
Call example:
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>"Response example: 204 No Content: No response body (deleted).
PATCH /v1/webhooks/{webhookId}/signature
Rotate the Webhook signing secret: the old secret becomes invalid immediately and the response returns the new secret; use when a leak is suspected or for regular rotation.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
webhookId | path | string | Yes | — | Webhook ID. |
Output: Returns the updated webhook (signatureKey is the new value):
| Field | Type | Description |
|---|---|---|
$id | string | Webhook ID。 |
$createdAt | string | Creation time (ISO 8601). |
$updatedAt | string | Last update time (ISO 8601). |
name | string | Name (≤128 characters). |
url | string | Callback URL. |
events | string[] | Array of subscribed events (up to 100 items). |
security | boolean | Whether to enable peer TLS certificate verification. |
httpUser | string | Basic authentication username (≤256 characters). |
httpPass | string | Basic authentication password (≤256 characters). |
signatureKey | string | Signing secret: the platform uses it to sign callbacks, and the receiver uses it to verify the request origin; the rotation endpoint returns a new value. |
enabled | boolean | Whether it is enabled. |
logs | string | Error log of the most recent delivery failure. |
attempts | integer | Number of consecutive failures. |
Call example:
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>"Response example:
{
"$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.enterprise_biz_db.tables.customer_tickets.rows.*.create",
"databases.enterprise_biz_db.tables.customer_tickets.rows.*.update"
],
"security": true,
"httpUser": "hook-user",
"httpPass": "hook-pass",
"signatureKey": "f7c2e91b04da6f3c8e1b2a9d",
"enabled": true,
"logs": "",
"attempts": 0
}Errors and boundaries
Webhook event name not in the platform event enumeration: creation/update is rejected;
eventsexceeding 100 items is rejected.httpUser/httpPassonly support Basic authentication; callback failures are handled per the platform retry policy, and the retry queue is not managed within this API.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Webhooks.list / create / get / update / delete / updateSignature | /webhooks* |