Docs
Contents

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

Authentication and Permissions

See general conventions for authentication and request header conventions.

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 + pathPurpose
GET /webhooks / POST /webhooksWebhook list/create
GET|PUT|DELETE /webhooks/{webhookId}Webhook read/update/delete
PATCH /webhooks/{webhookId}/signatureRotate 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:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []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.
totalquerybooleanNoDefault trueWhen set to false, the response total is always 0, skipping counting.

Output: Returns webhookList (total + webhooks[]), with elements of webhook:

FieldTypeDescription
$idstringWebhook ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
namestringName (≤128 characters).
urlstringCallback URL.
eventsstring[]Array of subscribed events (up to 100 items).
securitybooleanWhether to enable peer TLS certificate verification.
httpUserstringBasic authentication username (≤256 characters).
httpPassstringBasic authentication password (≤256 characters).
signatureKeystringSigning 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.
enabledbooleanWhether it is enabled.
logsstringError log of the most recent delivery failure.
attemptsintegerNumber 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:

ParameterLocationTypeRequiredDefault/enumDescription
webhookIdbodystringYes—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.
urlbodystringYes—Callback URL.
namebodystringYes—Name, ≤128 characters.
eventsbodystring[]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.
enabledbodybooleanNo—Whether to enable, default false.
securitybodybooleanNo—Toggle for TLS certificate verification of the callback target, default false.
httpUserbodystringNo—Basic authentication username, ≤256 characters.
httpPassbodystringNo—Basic authentication password, ≤256 characters.

Output: Returns 201 + webhook (including signatureKey):

FieldTypeDescription
$idstringWebhook ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
namestringName (≤128 characters).
urlstringCallback URL.
eventsstring[]Array of subscribed events (up to 100 items).
securitybooleanWhether to enable peer TLS certificate verification.
httpUserstringBasic authentication username (≤256 characters).
httpPassstringBasic authentication password (≤256 characters).
signatureKeystringSigning 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.
enabledbooleanWhether it is enabled.
logsstringError log of the most recent delivery failure.
attemptsintegerNumber of consecutive failures.

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:

ParameterLocationTypeRequiredDefault/enumDescription
webhookIdpathstringYes—Webhook ID.

Output: Returns webhook:

FieldTypeDescription
$idstringWebhook ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
namestringName (≤128 characters).
urlstringCallback URL.
eventsstring[]Array of subscribed events (up to 100 items).
securitybooleanWhether to enable peer TLS certificate verification.
httpUserstringBasic authentication username (≤256 characters).
httpPassstringBasic authentication password (≤256 characters).
signatureKeystringSigning 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.
enabledbooleanWhether it is enabled.
logsstringError log of the most recent delivery failure.
attemptsintegerNumber 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:

ParameterLocationTypeRequiredDefault/enumDescription
webhookIdpathstringYes—Webhook ID.
namebodystringYes—Name, ≤128 characters (required).
urlbodystringYes—Callback URL (required).
eventsbodystring[]Yes—Array of subscribed events, up to 100 items (required).
enabledbodybooleanNo—Whether to enable.
securitybodybooleanNo—TLS certificate verification toggle.
httpUserbodystringNo—Basic authentication username, ≤256 characters.
httpPassbodystringNo—Basic authentication password, ≤256 characters.

Output: Returns the updated webhook:

FieldTypeDescription
$idstringWebhook ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
namestringName (≤128 characters).
urlstringCallback URL.
eventsstring[]Array of subscribed events (up to 100 items).
securitybooleanWhether to enable peer TLS certificate verification.
httpUserstringBasic authentication username (≤256 characters).
httpPassstringBasic authentication password (≤256 characters).
signatureKeystringSigning 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.
enabledbooleanWhether it is enabled.
logsstringError log of the most recent delivery failure.
attemptsintegerNumber 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:

ParameterLocationTypeRequiredDefault/enumDescription
webhookIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
webhookIdpathstringYes—Webhook ID.

Output: Returns the updated webhook (signatureKey is the new value):

FieldTypeDescription
$idstringWebhook ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
namestringName (≤128 characters).
urlstringCallback URL.
eventsstring[]Array of subscribed events (up to 100 items).
securitybooleanWhether to enable peer TLS certificate verification.
httpUserstringBasic authentication username (≤256 characters).
httpPassstringBasic authentication password (≤256 characters).
signatureKeystringSigning 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.
enabledbooleanWhether it is enabled.
logsstringError log of the most recent delivery failure.
attemptsintegerNumber 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

Correspondence with the Server SDK

service.methodEndpoint
Webhooks.list / create / get / update / delete / updateSignature/webhooks*