Level up Your Webhook Security With Appwrite 0.15

Don’t Know What Appwrite Is?

Appwrite is an Open-Source BaaS, which sounds complex but is actually simple. We abstract most of the tedious, repetitive tasks away from you, such as Authentication, Databases, Storage and more. So instead of reinventing the wheel, you can concentrate on building your project.

Why Should I Validate Webhooks?

Webhooks send a lot of sensitive data to your backend. It takes just one person to find your webhook URL to send invalid and insecure data to your backend; this could result in someone telling your backend that someone created a session for example (when they didn’t) and could give them access to other user’s accounts. Another thing they could do is say that database entries were edited, which could poison your local copy on the backend allowing for fraudilent data. This is just the tip of the iceberg of what could happen if you don’t validate your webhooks.

How Do I Validate Webhooks, Then?

Validating webhooks couldn't be easier! You need to run the webhook payload through the same algorithm used to generate the signature in the header and then compare the two. If they match, the webhook is confirmed to come from your Appwrite instance.

In order to begin enabling validation your going to need to grab your webhook’s signature key, this can be found in the dashboard in your webhook’s properties page. For those of you wondering what a signature key is, it’s the key that is used to hash the payload and generate the ‘x-appwrite-webhook-signature’ header. Please note that you should NEVER share or release this key as it allows a third party to forge the payload signature. You should store this in a secure place on your backend, either in a .env file or a secrets manager. If this key ever gets leaked you can always change the key within your webhook’s settings.

To generate the hash to compare, you'll need to run the payload appended to the URL through an HMAC SHA1 Function using the signature key, then convert the result into Base64. After that you compare it to the ‘x-appwrite-webhook-signature’ header. Implementing this will be different depending on the language your backend is written.
For example, nodeJS will look like so:

const crypto = require('crypto');
let token = crypto.createHmac("sha1", process.env.WEBHOOK_SIG_KEY)
    .update(`https://yourwebhookurl/test${JSON.stringify(payload.body)}`) // Make sure there isn't a space between the URL and body.
    .digest().toString('base64');

if (token !== payload.headers['x-appwrite-webhook-signature']) {
    throw new Error('Failed authentication check.')
}

and in PHP, it may look like this:

<?php

$token = base64_encode(hash_hmac('sha1', 'https://yourwebhookurl/test' . $payload.body, getenv('WEBHOOK_SIG_KEY'), true));

if ($token != $payload.headers['x-appwrite-webhook-signature']) {
    throw new Error('Failed authentication check.');
}

Please remember that this code may differ from what you write in your backend.

📚 Learn More

Webhook validation is only the tip of the iceberg of what Appwrite 0.15 offers! Check out the official release notes, and stay tuned for more blog posts! In upcoming weeks we will describe all features in their separate blogposts to give them well-deserved spotlights. We can't wait to see what you build with Appwrite! 😎