Verify Signatures

When your webhook has a secret configured, every delivery includes an X-Way-Signature header:

X-Way-Signature: qL2vXt0k9pZ8w1Jm3RfB6yUcNdEaGhSiOo4T7rVKxAY=

It is the HMAC-SHA256 of the request body, keyed with your webhook secret, base64-encoded. Recompute it and compare to prove the request came from Way and wasn’t tampered with.

Compute the HMAC over the raw request body bytes - not a re-serialized copy. Parsing the JSON and re-stringifying it (JSON.stringify(req.body)) can produce different bytes than what Way signed (number formatting, key handling, and unicode escaping vary by language and parser), which makes verification fail intermittently or - worse - pass only by coincidence. Capture the body before your framework parses it.

Node.js (Express)

import crypto from "crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/way",
  // keep the raw bytes for signature verification
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.get("X-Way-Signature") ?? "";
    const expected = crypto
      .createHmac("sha256", process.env.WAY_WEBHOOK_SECRET)
      .update(req.body) // req.body is a Buffer of the raw bytes
      .digest("base64");

    const valid =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

    if (!valid) return res.status(401).end();

    res.status(200).end(); // acknowledge fast...
    const { event, payload } = JSON.parse(req.body); // ...then process
    handleEvent(event, payload);
  }
);

Python (Flask)

import base64, hashlib, hmac, os
from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/way")
def way_webhook():
    raw = request.get_data()  # raw bytes, before JSON parsing
    expected = base64.b64encode(
        hmac.new(os.environ["WAY_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256).digest()
    ).decode()

    if not hmac.compare_digest(request.headers.get("X-Way-Signature", ""), expected):
        return "", 401

    body = request.get_json()
    handle_event(body["event"], body["payload"])
    return "", 200

Pitfalls

Body re-serialization - the most common failure. Frameworks that eagerly parse JSON (Express’s express.json(), some serverless runtimes) must be configured to expose the raw body for the webhook route.
Proxies that mutate the body - anything that re-encodes or pretty-prints the JSON between Way and your handler breaks the signature. Verify at the first hop that sees the raw bytes.
Missing header - deliveries carry X-Way-Signature only when the webhook has a secret configured. If you expect it and it’s absent, treat the request as unauthenticated.
String comparison - use a timing-safe comparison (crypto.timingSafeEqual, hmac.compare_digest) rather than ===.

Getting started

Event catalog

Verify Signatures

Node.js (Express)

Python (Flask)

Pitfalls

​Node.js (Express)

​Python (Flask)

​Pitfalls

Node.js (Express)

Python (Flask)

Pitfalls