Skip to content
RelayDocumentation

GuidesCore concepts

Verifying signatures

Check that each request comes from Relay and hasn't been tampered with or replayed.

Anyone who knows your endpoint URL can send it a request. Relay signs every delivery so you can reject requests that don't come from Relay.

The signature header

Relay-Signature: t=1760434272,v2=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t is the Unix timestamp of the attempt.
  • v2 is an HMAC-SHA256 of {t}.{raw body}, using the endpoint's signing secret as the key.

Verify with the SDK

The SDKs check the signature, the timestamp and parse the body in one call. Use the raw request body: parsing and serializing JSON again changes the bytes and breaks the signature.

import { verifyWebhook } from "@relay/sdk";
 
const event = verifyWebhook({
  payload: rawBody,
  header: request.headers.get("relay-signature"),
  secret: process.env.RELAY_WEBHOOK_SECRET,
});

Verify manually

If there's no SDK for your language, follow these steps:

Split the header

Read t and v2 from the Relay-Signature header.

Check the timestamp

Reject the request if t is more than five minutes away from your server time. This blocks replay attacks.

Compute the expected signature

import { createHmac, timingSafeEqual } from "node:crypto";
 
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");

Compare in constant time

const valid = timingSafeEqual(Buffer.from(expected), Buffer.from(v2));

Never compare with ===: it leaks timing information.

v1 signatures are deprecated

The old X-Relay-Hmac header keeps working until January 31, 2027. Move to Relay-Signature before then. See the changelog.