Signatures
Anybody can send a request to your address. The signature proves that EzReach sent it and that nobody changed it on the way. Check it on every request.
The signature header
Header
EzReach-Signature: t=1760868000,v1=5257a869e7ec...tis the time EzReach signed the request, in Unix seconds.v1is the HMAC-SHA256, in lower-case hex, of the text<t>.<raw body>: the time, a dot, then the exact bytes of the body. The key is your whole signing secret, including thewhsec_at the start.- A retry signs the same body again with a new
t.
How to check it
- Read the raw body as it arrived. Do not parse it and write it out again: a changed space breaks the signature.
- Take
tand everyv1from the header. There can be more than onev1. - Compute the HMAC-SHA256 of
<t>.<raw body>with your secret. - Compare it with each
v1in constant time (crypto.timingSafeEqualin Node.js). Accept the request if any one matches. - Refuse the request if
tis more than 5 minutes away from your own clock. That stops somebody from replaying a request they captured earlier. - Ignore an event
idyou have already handled. Then answer2xx.
Node.js (Express)
const crypto = require("node:crypto");
const express = require("express");
const app = express();
const SECRET = process.env.EZREACH_WEBHOOK_SECRET; // whsec_...
// Use the RAW body: sign what arrived, not what JSON.parse gives back.
app.post("/webhooks/ezreach", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("EzReach-Signature") || "";
let t = null;
const signatures = [];
for (const part of header.split(",")) {
const [key, value] = part.trim().split("=");
if (key === "t") t = Number(value);
if (key === "v1") signatures.push(value);
}
const raw = req.body.toString("utf8");
const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${raw}`).digest("hex");
// During a secret rotation the header holds two v1 values: accept the request when any one matches.
const matches = signatures.some(
(sig) => sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
);
const fresh = t && Math.abs(Date.now() / 1000 - t) <= 300;
if (!matches || !fresh) return res.status(400).send("bad signature");
const event = JSON.parse(raw); // { id, type, created_at, data }
// Ignore an id you have already handled. Answer 2xx within 10 seconds and do slow work afterwards.
res.sendStatus(200);
});
Rotate the secret
If a secret may have leaked, or on a schedule, choose Rotate secret on the endpoint in Settings > Developers > Webhooks. The new secret is shown once.
- From that moment every request is signed with the new secret.
- For the next 24 hours it is also signed with the previous secret, as a second
v1(the new one first). The endpoint shows until when the previous secret still signs. - If your code accepts any one matching
v1, as the example does, your server keeps working with either secret. Put the new secret on your server at any time that day. - After 24 hours only the new secret signs. Rotating again inside the 24 hours drops the oldest: only the secret you just replaced signs next to the new one.
During the overlap
EzReach-Signature: t=1760868000,v1=<signed with the new secret>,v1=<signed with the previous secret>
