Verify Webhooks

We are going to use the Svix open-source library to verify webhooks. First, install the relevant libraries for your language:

npm install svix
// Or
yarn add svix

Next, verify webhooks using the code below. The payload is the raw (string) body of the request, and the headers are the headers passed in the request.

Remember to get the signature secret from the endpoint details in the console.

import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
"svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
"svix-timestamp": "1614265330",
"svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const payload = wh.verify(payload, headers);

If you need to verify manually, follow these instructions.

Each webhook call includes three headers with additional information that are used for verification:

• svix-id: The unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is resent (e.g., due to a previous failure).
• svix-timestamp: Timestamp in seconds since epoch.
• svix-signature: The Base64 encoded list of signatures (space delimited).

​

Constructing the Signed Content

The content to sign is composed by concatenating the ID, timestamp, and payload, separated by the full-stop character (.). In code, it will look something like this:

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;

Where body is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying.

​

Determining the Expected Signature

We use HMAC with SHA-256 to sign webhooks.

To calculate the expected signature, HMAC the signedContent from above using the base64 portion of your signing secret (this is the part after the whsec_ prefix) as the key. For example, if your secret is whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw, use MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.

For example, this is how you can calculate the signature in Node.js:

const crypto = require('crypto');

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

// Need to base64 decode the secret
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const signature = crypto
.createHmac('sha256', secretBytes)
.update(signedContent)
.digest('base64');

console.log(signature);

This generated signature should match one of the ones sent in the svix-signature header.

The svix-signature header is a list of space-delimited signatures with version identifiers. The list is typically one item but can contain multiple signatures, like this:

v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=

Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature.

Please note that to compare the signatures it’s recommended to use a constant-time string comparison method in order to prevent timing attacks.

​

Verify timestamp

We include the timestamp of the attempt in the svix-timestamp header. Compare this timestamp against your system timestamp to ensure it’s within an acceptable tolerance to prevent replay attacks.