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.