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
Each time the platform pushes an event to the target url, it computes an HMAC-SHA1/SHA256 signature of the request payload using that Webhook's signatureKey and writes it into the request header; the receiving service should verify the signature before processing business logic. When delivery fails consecutively, the platform automatically increments the attempts counter and writes the most recent peer response error into the logs field for troubleshooting.
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.tables.update",
"databases.collections.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.tables.update), otherwise creation/update is rejected. |
enabled | body | boolean | No | — | Whether to enable, default false. |
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:
curl -X POST "https://<your-endpoint>/v1/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"webhookId": "wh_billing_events",
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase",
"events": ["databases.tables.update", "databases.collections.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.tables.update",
"databases.collections.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.tables.update",
"databases.collections.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, the rest are optional.
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 | — | Whether to enable. |
security | body | boolean | No | — | TLS certificate verification toggle. |
httpUser | body | string | No | — | Basic authentication username, ≤256 characters. |
httpPass | body | string | No | — | Basic authentication password, ≤256 characters. |
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:
curl -X PUT "https://<your-endpoint>/v1/webhooks/wh_billing_events" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "计费事件回调",
"url": "https://api.example.com/hooks/agentbase-v2",
"events": ["databases.tables.update"],
"enabled": true
}'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.tables.update"
],
"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.tables.update",
"databases.collections.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* |