While using our official libraries is the recommended and most straightforward method to verify webhooks (as discussed in the previous verification guide), there may be situations where you need to verify them manually. This section explains the manual verification process in detail.

The recommended way to verify webhooks is using our official libraries. Please consider that implementation strategy first.

​
Verifying Signatures Manually

Each webhook call includes three headers that are crucial for verifying authenticity:

  • webhook-id: A unique message identifier for the webhook message. This value is unique across all messages. If a webhook is resent (due to a previous failure), the webhook-id will remain the same.

  • webhook-timestamp: The timestamp of the attempt in seconds since the Unix epoch.

  • webhook-signature: A Base64-encoded list of signatures (space-delimited).

You will use these headers, along with the raw request body, to generate and compare the expected signature.

​
Constructing the Signed Content

The content to sign is created by concatenating the id, timestamp, and payload (raw body of the request) with a . character between them:

const signedContent = `${webhook_id}.${webhook_timestamp}.${body}`;

It’s critical that you use the raw request body here. Any modifications (such as re-stringifying a parsed JSON body) will change the content and result in a signature mismatch.

​
Determining the Expected Signature

Straddle uses an HMAC with SHA-256 to sign its webhooks.

To calculate the expected signature:

  1. Extract the portion of your signing secret after the whsec_ prefix.

  2. Base64-decode that portion to get your key bytes.

  3. Compute the HMAC using the decoded key and the signedContent.

  4. Compare the result against the provided webhook-signature values.

​
Example in Node.js

const crypto = require('crypto');

const svix_id = "msg_p5jXN8AQM9LWM0D4loKWxJek";
const svix_timestamp = "1614265330";
const body = '{"test": 2432232314}';
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

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

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

console.log(signature);
// This signature should match one of those found in the `webhook-signature` header.

​
Comparing Signatures

The webhook-signature header often looks like this:

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

Each signature is prefixed by a version identifier and a comma, such as v1,. To verify, remove the prefix (e.g., v1,) and compare the remaining Base64 string to your computed signature.

Use a constant-time comparison method to compare signatures and prevent timing attacks.

​
Verifying the Timestamp

The webhook-timestamp header includes the timestamp of the attempt. Make sure this timestamp is close to your current time (within a certain allowed skew, like a few minutes) to prevent replay attacks.

​
Example Signatures

Here is an example you can use to validate your manual verification logic. Note that this may fail verification due to an old timestamp, and that’s expected if you’re strictly enforcing freshness.

const secret = 'whsec_plJ3nmyCDGBKInavdOK15jsl';
const payload = '{"event_type":"ping","data":{"success":true}}';
const msg_id = 'msg_loFOjxBNrRLzqYUe';
const timestamp = '1731705121';

// The expected signature would be generated following the steps described above.
// Replace with actual code to verify and compare the result.

You can also use the open-source Standard Webhooks simulation tool to generate as many examples as needed.