Docs
Skip to content

Platform

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

Raw

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:

  1. Navigate to your project's Settings page.
  2. Select the Webhooks tab.
  3. Click Create webhook.
  4. Enter a Name and the POST URL for your webhook endpoint.
  5. Click Add an event to choose the events that should trigger the webhook.
  6. Optionally, enable Certificate verification (SSL/TLS) and set HTTP authentication credentials to secure your endpoint.
  7. Click Create webhook.

Create webhook screen
Create webhook screen

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.

List webhooks

Get a webhook

Update a webhook

Delete a webhook

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.

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.

HeaderDescription
X-Appwrite-Webhook-IdThe ID of the Webhook who triggered the event.
X-Appwrite-Webhook-EventsNames of the events that triggered this delivery.
X-Appwrite-Webhook-NameName of the webhook as specified in your app settings and events list.
X-Appwrite-Webhook-User-IdThe 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-IdThe ID of the project who owns the Webhook and API call.
X-Appwrite-Webhook-SignatureThe HMAC-SHA1 signature of the payload. This is used to verify the authenticity of the payload.
User-AgentEach 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:

  1. Concatenate the webhook URL and the request body (no spaces in between).
  2. Generate an HMAC-SHA1 hash of the concatenated string using your webhook's signature key.
  3. Base64 encode the resulting hash.
  4. Compare the result to the X-Appwrite-Webhook-Signature header value. If they match, the payload is authentic.

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.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.