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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdtis the Unix timestamp of the attempt.v2is 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,
});from relay import verify_webhook
event = verify_webhook(
payload=request.body,
header=request.headers["Relay-Signature"],
secret=os.environ["RELAY_WEBHOOK_SECRET"],
)event, err := relay.VerifyWebhook(body, r.Header.Get("Relay-Signature"), secret)
if err != nil {
http.Error(w, "invalid signature", http.StatusBadRequest)
return
}event = Relay::Webhook.verify(
payload: request.raw_post,
header: request.headers["Relay-Signature"],
secret: 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.