Webhook signatures move to Ed25519
Why we switched from shared HMAC secrets to public key signatures, and how to verify them in a few lines of TypeScript.
On this page4 sections

Every webhook Relaywave sends carries a signature, so your endpoint can prove the request came from us. Until now that signature was an HMAC with a secret we shared with you. Starting today, new endpoints get Ed25519 signatures instead, and you verify them with a public key.
What was wrong with HMAC
Nothing in the math. The problem was the secret. To verify an HMAC you need the same secret we sign with, which means:
- the secret lives in your environment variables, your CI and often a teammate’s
.env - rotating it needs a deploy on your side at the exact moment we switch
- a leaked secret lets anyone send you requests that pass verification
With Ed25519 we keep the private key. You only hold the public key, and a leaked public key lets nobody sign anything.
The new headers
Each delivery now has three headers:
Relaywave-Id: msg_01J9X4TQ8K2M
Relaywave-Timestamp: 1759830000
Relaywave-Signature: v2,MEUCIQDf...
The signed payload is id.timestamp.body, joined with dots. Including the timestamp lets you reject replays older than five minutes.
Verify in TypeScript
The SDK does all of this for you:
import { verifyWebhook } from "@relaywave/node";
export async function POST(request: Request) {
const body = await request.text();
const event = await verifyWebhook(body, request.headers, {
publicKey: process.env.RELAYWAVE_PUBLIC_KEY!,
toleranceSeconds: 300,
});
// event is typed and safe to trust here
return new Response(null, { status: 204 });
}
Without the SDK, Node’s built-in crypto is enough:
import { createPublicKey, verify } from "node:crypto";
const key = createPublicKey(process.env.RELAYWAVE_PUBLIC_KEY!);
function isValid(id: string, timestamp: string, body: string, header: string) {
const signature = Buffer.from(header.replace("v2,", ""), "base64");
const payload = Buffer.from(`${id}.${timestamp}.${body}`);
return verify(null, payload, key, signature);
}
Existing endpoints
Nothing changes until you opt in. Open Endpoints → Signing, click Switch to Ed25519, and for 7 days every delivery carries both the old v1 HMAC and the new v2 signature. Deploy the new check, then turn off v1.