Browse the docs

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.

Header
EzReach-Signature: t=1760868000,v1=5257a869e7ec...
  • t is the time EzReach signed the request, in Unix seconds.
  • v1 is 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 the whsec_ at the start.
  • A retry signs the same body again with a new t.

How to check it

  1. Read the raw body as it arrived. Do not parse it and write it out again: a changed space breaks the signature.
  2. Take t and every v1 from the header. There can be more than one v1.
  3. Compute the HMAC-SHA256 of <t>.<raw body> with your secret.
  4. Compare it with each v1 in constant time (crypto.timingSafeEqual in Node.js). Accept the request if any one matches.
  5. Refuse the request if t is more than 5 minutes away from your own clock. That stops somebody from replaying a request they captured earlier.
  6. Ignore an event id you have already handled. Then answer 2xx.
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>