Webhook signature verification with HMAC-SHA256

Every webhook request from Yoshi is signed with HMAC-SHA256 so you can verify it came from Yoshi and hasn’t been tampered with. Always verify signatures before processing events.

Quick start

The fastest way to verify webhooks is with the SDK:

import { verifySignature } from "@yoshi-ai/sdk/lib/webhooks";

app.post("/webhooks/yoshi", (req, res) => {
  const isValid = verifySignature(
    req.body,
    req.headers["x-yoshi-signature"],
    req.headers["x-yoshi-timestamp"],
    process.env.WEBHOOK_SECRET,
  );

  if (!isValid) return res.status(400).send("Invalid signature");

  const event = JSON.parse(req.body);
  // Process event asynchronously...
  res.status(200).send("OK");
});

from yoshi.lib.webhooks import verify_signature

@app.post("/webhooks/yoshi")
def handle_webhook(request):
    is_valid = verify_signature(
        payload=request.body,
        signature=request.headers["x-yoshi-signature"],
        timestamp=request.headers["x-yoshi-timestamp"],
        secret=os.environ["WEBHOOK_SECRET"],
    )

    if not is_valid:
        return Response(status_code=400)

    event = request.json()
    # Process event asynchronously...
    return Response(status_code=200)

How signing works

Every webhook request includes two headers:

Header	Example	Description
`x-yoshi-signature`	`a1b2c3d4e5f6...`	HMAC-SHA256 hex digest of the signed content
`x-yoshi-timestamp`	`1714444800`	Unix timestamp (seconds) when the event was sent

The signature is computed as:

signed_content = "{timestamp}.{raw_body}"
signature = hex(HMAC-SHA256(secret, signed_content))

Where secret is your webhook signing secret (starts with whsec_), timestamp is the value of the x-yoshi-timestamp header, and raw_body is the raw request body string.

You must use the raw request body for verification, not a parsed-then-serialized version. Most frameworks parse JSON automatically — make sure you capture the raw body before parsing.

Framework examples

import express from "express";
import { verifySignature } from "@yoshi-ai/sdk/lib/webhooks";

const app = express();

// Capture raw body for signature verification
app.post("/webhooks/yoshi", express.raw({ type: "application/json" }), (req, res) => {
  const isValid = verifySignature(
    req.body,
    req.headers["x-yoshi-signature"] as string,
    req.headers["x-yoshi-timestamp"] as string,
    process.env.WEBHOOK_SECRET!,
  );

  if (!isValid) return res.status(400).send("Invalid signature");

  const event = JSON.parse(req.body.toString());
  console.log(`Received ${event.type}:`, event.id);
  res.status(200).send("OK");
});

// app/api/webhooks/yoshi/route.ts
import { verifySignature } from "@yoshi-ai/sdk/lib/webhooks";

export async function POST(request: Request) {
  const body = await request.text();

  const isValid = verifySignature(
    body,
    request.headers.get("x-yoshi-signature")!,
    request.headers.get("x-yoshi-timestamp")!,
    process.env.WEBHOOK_SECRET!,
  );

  if (!isValid) {
    return new Response("Invalid signature", { status: 400 });
  }

  const event = JSON.parse(body);
  console.log(`Received ${event.type}:`, event.id);
  return new Response("OK", { status: 200 });
}

from fastapi import FastAPI, Request, Response
from yoshi.lib.webhooks import verify_signature
import os

app = FastAPI()

@app.post("/webhooks/yoshi")
async def handle_webhook(request: Request):
    body = await request.body()

    is_valid = verify_signature(
        payload=body,
        signature=request.headers["x-yoshi-signature"],
        timestamp=request.headers["x-yoshi-timestamp"],
        secret=os.environ["WEBHOOK_SECRET"],
    )

    if not is_valid:
        return Response(status_code=400)

    event = await request.json()
    print(f"Received {event['type']}: {event['id']}")
    return Response(status_code=200)

# views.py
import json
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from yoshi.lib.webhooks import verify_signature
import os

@csrf_exempt
def webhook_handler(request):
    is_valid = verify_signature(
        payload=request.body,
        signature=request.headers["X-Yoshi-Signature"],
        timestamp=request.headers["X-Yoshi-Timestamp"],
        secret=os.environ["WEBHOOK_SECRET"],
    )

    if not is_valid:
        return HttpResponse(status=400)

    event = json.loads(request.body)
    print(f"Received {event['type']}: {event['id']}")
    return HttpResponse(status=200)

Replay protection

The SDK rejects webhooks with timestamps older than 5 minutes by default. This prevents replay attacks where an attacker resends a captured webhook request. You can customize this tolerance:

verifySignature(payload, signature, timestamp, secret, {
  tolerance: 600, // 10 minutes
});

verify_signature(
    payload=payload,
    signature=signature,
    timestamp=timestamp,
    secret=secret,
    tolerance=600,  # 10 minutes
)

Manual verification

If you prefer to verify signatures without the SDK:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(body: string, signature: string, timestamp: string, secret: string): boolean {
  // Check timestamp is within tolerance (5 minutes)
  const ts = parseInt(timestamp, 10);
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - ts) > 300) return false;

  // Compute expected signature
  const signedPayload = `${timestamp}.${body}`;
  const expected = createHmac("sha256", secret).update(signedPayload).digest("hex");

  // Constant-time comparison
  const sigBuf = Buffer.from(signature, "utf-8");
  const expectedBuf = Buffer.from(expected, "utf-8");
  if (sigBuf.length !== expectedBuf.length) return false;

  return timingSafeEqual(sigBuf, expectedBuf);
}

import hashlib
import hmac
import time

def verify_webhook(body: str, signature: str, timestamp: str, secret: str) -> bool:
    # Check timestamp is within tolerance (5 minutes)
    ts = int(timestamp)
    now = int(time.time())
    if abs(now - ts) > 300:
        return False

    # Compute expected signature
    signed_payload = f"{timestamp}.{body}".encode("utf-8")
    expected = hmac.new(
        secret.encode("utf-8"),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(signature, expected)

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"math"
	"strconv"
	"time"
)

func VerifyWebhook(body, signature, timestamp, secret string) bool {
	// Check timestamp is within tolerance (5 minutes)
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}
	now := time.Now().Unix()
	if math.Abs(float64(now-ts)) > 300 {
		return false
	}

	// Compute expected signature
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "." + body))
	expected := hex.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(signature), []byte(expected))
}

Always use constant-time comparison (timingSafeEqual in Node.js, hmac.compare_digest in Python, hmac.Equal in Go) to prevent timing attacks. Never use === or == for signature comparison.

Secret rotation

When you rotate your signing secret, there is a brief window where both the old and new secrets are valid. During this window, Yoshi signs webhooks with both secrets. Your verification logic should try the new secret first, then fall back to the old secret. The SDK handles this automatically if you pass an array of secrets:

const secrets = [process.env.WEBHOOK_SECRET_NEW, process.env.WEBHOOK_SECRET_OLD];

const isValid = secrets.some((secret) =>
  verifySignature(req.body, req.headers["x-yoshi-signature"], req.headers["x-yoshi-timestamp"], secret)
);

secrets = [os.environ["WEBHOOK_SECRET_NEW"], os.environ["WEBHOOK_SECRET_OLD"]]

is_valid = any(
    verify_signature(
        payload=request.body,
        signature=request.headers["x-yoshi-signature"],
        timestamp=request.headers["x-yoshi-timestamp"],
        secret=secret,
    )
    for secret in secrets
)

Getting Started

Reference

SDKs

Concepts

Webhooks

Use Cases

Tools

Resources

Webhook signature verification with HMAC-SHA256

Quick start

How signing works

Framework examples

Replay protection

Manual verification

Secret rotation

​Quick start

​How signing works

​Framework examples

​Replay protection

​Manual verification

​Secret rotation

Quick start

How signing works

Framework examples

Replay protection

Manual verification

Secret rotation