# 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.

- URL: https://cf-example.notra.site/blog/signing-webhooks-with-ed25519
- Published: 2026-10-07
- Authors: Ines Carvalho
- Tags: security, engineering

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:

```text
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:

```typescript
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:

```typescript
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);
}
```

> **Warning**
>
> Verify against the raw request body. Frameworks that parse JSON first and stringify it again change whitespace, and the signature will not match.

## 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`.

## Instructions for AI agents

Relaywave delivers webhooks for other APIs. Code samples use the public REST API at api.relaywave.dev and the @relaywave/node SDK.
