Webhooks_
Leverage webhooks in the Appwrite platform for real-time updates. Learn how to configure, manage, and integrate webhooks to keep your applications in sync.
3 min read
Webhooks allow you to build or set up integrations which subscribe to certain events on Appwrite. When one of those events is triggered, we'll send an HTTP POST payload to the webhook's configured URL. Webhooks can be used to purge cache from CDN, calculate data or send a Slack notification. You're only limited by your imagination.
Getting started
To add a webhook from the Appwrite Console:
- Navigate to your project's Settings page.
- Select the Webhooks tab.
- Click Create webhook.
- Enter a Name and the POST URL for your webhook endpoint.
- Click Add an event to choose the events that should trigger the webhook.
- Optionally, enable Certificate verification (SSL/TLS) and set HTTP authentication credentials to secure your endpoint.
- Click Create webhook.
Manage webhooks with a Server SDK
You can also manage webhooks programmatically using a Server SDK. This requires an API key with the webhooks.read and webhooks.write scopes.
Create a webhook
The response includes a secret field containing the webhook's signing key. This is the only time the secret is returned, so store it securely right away.
import { Client, Webhooks, ID } from 'node-appwrite';
const client = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('<PROJECT_ID>') .setKey('<YOUR_API_KEY>');
const webhooks = new Webhooks(client);
const result = await webhooks.create({ webhookId: ID.unique(), url: 'https://example.com/webhook', name: 'My Webhook', events: ['users.*.create'], tls: true, secret: '<SECRET>' // optional});
console.log(result.secret); // store it now, not returned againList webhooks
import { Client, Webhooks } from 'node-appwrite';
const client = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('<PROJECT_ID>') .setKey('<YOUR_API_KEY>');
const webhooks = new Webhooks(client);
const result = await webhooks.list({ queries: [], // optional total: false // optional});Get a webhook
import { Client, Webhooks } from 'node-appwrite';
const client = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('<PROJECT_ID>') .setKey('<YOUR_API_KEY>');
const webhooks = new Webhooks(client);
const result = await webhooks.get({ webhookId: '<WEBHOOK_ID>'});Update a webhook
import { Client, Webhooks } from 'node-appwrite';
const client = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('<PROJECT_ID>') .setKey('<YOUR_API_KEY>');
const webhooks = new Webhooks(client);
const result = await webhooks.update({ webhookId: '<WEBHOOK_ID>', name: 'Updated Webhook', url: 'https://example.com/webhook-updated', events: ['users.*.update'], tls: true});Delete a webhook
import { Client, Webhooks } from 'node-appwrite';
const client = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('<PROJECT_ID>') .setKey('<YOUR_API_KEY>');
const webhooks = new Webhooks(client);
await webhooks.delete({ webhookId: '<WEBHOOK_ID>'});Rotate signing key
Calling updateSecret without a value generates a new random signing key. You can optionally provide your own secret (8-256 characters) to set a specific key, which is useful for zero-downtime key rotation.
import { Client, Webhooks } from 'node-appwrite';
const client = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('<PROJECT_ID>') .setKey('<YOUR_API_KEY>');
const webhooks = new Webhooks(client);
const result = await webhooks.updateSecret({ webhookId: '<WEBHOOK_ID>', secret: '<SECRET>' // optional});Payload
Each event type has a specific payload format with the relevant event information. All event payloads mirror the payloads for the API payload which parallel to the event types.
Headers
HTTP requests made to your webhook's configured URL endpoint will contain several special headers.
| Header | Description |
|---|---|
| X-Appwrite-Webhook-Id | The ID of the Webhook who triggered the event. |
| X-Appwrite-Webhook-Events | Names of the events that triggered this delivery. |
| X-Appwrite-Webhook-Name | Name of the webhook as specified in your app settings and events list. |
| X-Appwrite-Webhook-User-Id | The user ID of the user who triggered the event. Returns an empty string if an API key triggered the event. Note that events like account.create or account.sessions.create are performed by guest users and will not return any user ID. If you still need the user ID for these events, you can find it in the event payload. |
| X-Appwrite-Webhook-Project-Id | The ID of the project who owns the Webhook and API call. |
| X-Appwrite-Webhook-Signature | The HMAC-SHA1 signature of the payload. This is used to verify the authenticity of the payload. |
| User-Agent | Each request made by Appwrite will be 'Appwrite-Server'. |
Verification
You can verify that a webhook request genuinely came from your Appwrite instance using the X-Appwrite-Webhook-Signature header. The signature key can be found in your webhook's properties in the Appwrite Console.
To verify the signature:
- Concatenate the webhook URL and the request body (no spaces in between).
- Generate an HMAC-SHA1 hash of the concatenated string using your webhook's signature key.
- Base64 encode the resulting hash.
- Compare the result to the
X-Appwrite-Webhook-Signatureheader value. If they match, the payload is authentic.
import crypto from 'crypto';
function verifyWebhook(req, signatureKey) { const url = 'https://example.com/webhook'; // Your webhook URL const payload = req.body; // Raw request body as string const signature = req.headers['x-appwrite-webhook-signature'];
const generated = crypto .createHmac('sha1', signatureKey) .update(url + payload) .digest('base64');
return crypto.timingSafeEqual( Buffer.from(generated), Buffer.from(signature) );}Events
Appwrite has events that fire when a resource changes. These events cover all Appwrite resources and can reflect create, update, and delete actions. You can specify one or many events to subscribe to with webhooks.
| Name | Description |
|---|---|
teams.* | This event triggers on any teams event. Returns Team Object |
teams.*.create | This event triggers when a team is created. Returns Team Object |
teams.*.delete | This event triggers when a team is deleted. Returns Team Object |
teams.*.memberships.* | This event triggers on any team memberships event. Returns Membership Object |
teams.*.memberships.*.create | This event triggers when a membership is created. Returns Membership Object |
teams.*.memberships.*.delete | This event triggers when a membership is deleted. Returns Membership Object |
teams.*.memberships.*.update | This event triggers when a membership is updated. Returns Membership Object |
teams.*.memberships.*.update.status | This event triggers when a team memberships status is updated. Returns Membership Object |
teams.*.update | This event triggers when a team is updated. Returns Team Object |
teams.*.update.prefs | This event triggers when a team's preferences are updated. Returns Team Object |
users.* | This event triggers on any user's event. Returns User Object |
users.*.create | This event triggers when a user is created. Returns User Object |
users.*.delete | This event triggers when a user is deleted. Returns User Object |
users.*.recovery.* | This event triggers on any user's recovery token event. Returns Token Object |
users.*.recovery.*.create | This event triggers when a recovery token for a user is created. Returns Token Object |
users.*.recovery.*.update | This event triggers when a recovery token for a user is validated. Returns Token Object |
users.*.sessions.* | This event triggers on any user's sessions event. Returns Session Object |
users.*.sessions.*.create | This event triggers when a session for a user is created. Returns Session Object |
users.*.sessions.*.delete | This event triggers when a session for a user is deleted. Returns Session Object |
users.*.update | This event triggers when a user is updated. Returns User Object |
users.*.update.email | This event triggers when a user's email address is updated. Returns User Object |
users.*.update.name | This event triggers when a user's name is updated. Returns User Object |
users.*.update.password | This event triggers when a user's password is updated. Returns User Object |
users.*.update.prefs | This event triggers when a user's preferences is updated. Returns User Object |
users.*.update.status | This event triggers when a user's status is updated. Returns User Object |
users.*.verification.* | This event triggers on any user's verification token event. Returns Token Object |
users.*.verification.*.create | This event triggers when a verification token for a user is created. Returns Token Object |
users.*.verification.*.update | This event triggers when a verification token for a user is validated. Returns Token Object |
| Name | Description |
|---|---|
tablesdb.* | This event triggers on any database event. Returns Database Object |
tablesdb.*.tables.* | This event triggers on any table event. Returns Table Object |
tablesdb.*.tables.*.columns.* | This event triggers on any columns event. Returns Column Object |
tablesdb.*.tables.*.columns.*.create | This event triggers when a column is created. Returns Column Object |
tablesdb.*.tables.*.columns.*.update | This event triggers when a column is updated. Returns Column Object |
tablesdb.*.tables.*.columns.*.delete | This event triggers when a column is deleted. Returns Column Object |
tablesdb.*.tables.*.create | This event triggers when a table is created. Returns Table Object |
tablesdb.*.tables.*.delete | This event triggers when a table is deleted. Returns Table Object |
tablesdb.*.tables.*.rows.* | This event triggers on any rows event. Returns Row Object |
tablesdb.*.tables.*.rows.*.create | This event triggers when a row is created. Returns Row Object |
tablesdb.*.tables.*.rows.*.delete | This event triggers when a row is deleted. Returns Row Object |
tablesdb.*.tables.*.rows.*.update | This event triggers when a row is updated. Returns Row Object |
tablesdb.*.tables.*.rows.*.upsert | This event triggers when a row is upserted. Returns Row Object |
tablesdb.*.tables.*.indexes.* | This event triggers on any indexes event. Returns Index Object |
tablesdb.*.tables.*.indexes.*.create | This event triggers when an index is created. Returns Index Object |
tablesdb.*.tables.*.indexes.*.update | This event triggers when an index is updated. Returns Index Object |
tablesdb.*.tables.*.indexes.*.delete | This event triggers when an index is deleted. Returns Index Object |
tablesdb.*.tables.*.update | This event triggers when a table is updated. Returns Table Object |
tablesdb.*.create | This event triggers when a database is created. Returns Database Object |
tablesdb.*.delete | This event triggers when a database is deleted. Returns Database Object |
tablesdb.*.update | This event triggers when a database is updated. Returns Database Object |
| Name | Description |
|---|---|
buckets.* | This event triggers on any buckets event. Returns Bucket Object |
buckets.*.create | This event triggers when a bucket is created. Returns Bucket Object |
buckets.*.delete | This event triggers when a bucket is deleted. Returns Bucket Object |
buckets.*.files.* | This event triggers on any files event. Returns File Object |
buckets.*.files.*.create | Since the Appwrite SDK chunks files in 5MB increments, this event will trigger for each 5MB chunk. A file is fully uploaded when chunksTotal equals chunksUploaded. Returns File Object |
buckets.*.files.*.delete | This event triggers when a file is deleted. Returns File Object |
buckets.*.files.*.update | This event triggers when a file is updated. Returns File Object |
buckets.*.update | This event triggers when a bucket is updated. Returns Bucket Object |
| Name | Description |
|---|---|
functions.* | This event triggers on any functions event. Returns Function Object |
functions.*.create | This event triggers when a function is created. Returns Function Object |
functions.*.delete | This event triggers when a function is deleted. Returns Function Object |
functions.*.deployments.* | This event triggers on any deployments event. Returns Deployment Object |
functions.*.deployments.*.create | This event triggers when a deployment is created. Returns Deployment Object |
functions.*.deployments.*.delete | This event triggers when a deployment is deleted. Returns Deployment Object |
functions.*.deployments.*.update | This event triggers when a deployment is updated. Returns Deployment Object |
functions.*.executions.* | This event triggers on any executions event. Returns Execution Object |
functions.*.executions.*.create | This event triggers when an execution is created. Returns Execution Object |
functions.*.executions.*.delete | This event triggers when an execution is deleted. Returns Execution Object |
functions.*.executions.*.update | This event triggers when an execution is updated. Returns Execution Object |
functions.*.update | This event triggers when a function is updated. Returns Function Object |
| Name | Description |
|---|---|
providers.* | This event triggers on any providers event. Returns Provider Object |
providers.*.create | This event triggers when a provider is created. Returns Provider Object |
providers.*.delete | This event triggers when a provider is deleted. Returns Provider Object |
providers.*.update | This event triggers when a provider is updated. Returns Provider Object |
topics.* | This event triggers on any topic event. Returns Topic Object |
topics.*.create | This event triggers when a topic is created. Returns Topic Object |
topics.*.delete | This event triggers when a topic is deleted. Returns Topic Object |
topics.*.update | This event triggers when a topic is updated. Returns Topic Object |
topics.*.subscribers.*.create | This event triggers when a subscriber to a topic is created. Returns Topic Object |
topics.*.subscribers.*.delete | This event triggers when a subscriber to a topic is deleted. Returns Topic Object |
messages.* | This event triggers on any message event. Returns Message Object |
messages.*.create | This event triggers when a message is created. Returns Message Object |
messages.*.delete | This event triggers when a message is deleted. Returns Message Object |
messages.*.update | This event triggers when a message is updated. Returns Message Object |
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.