跳到正文
14 天免费试用,无需银行卡9 种语言176 种业务类型 · 50 个应用
ZH· USD
试用在线演示免费试用

此页面暂无简体中文版本,现以英文显示。

Verify the signature

Recompute the HMAC over the timestamp and the raw body, compare in constant time and reject old timestamps.

  • about 9 min

signature = "sha256=" + hex(HMAC_SHA256(secret, timestamp + "." + rawBody)). Use the raw request body — parsing and re-serialising the JSON changes the bytes and the signature will not match. Reject timestamps more than 5 minutes away from your clock.

app/api/zmle-webhook/route.ts (Next.js route handler)
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.ZMLE_WEBHOOK_SECRET ?? ""; // whsec_…

function verify(secret: string, timestamp: string, rawBody: string, given: string): boolean {
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false; // 5 minutes
  const expected = "sha256=" + createHmac("sha256", secret).update(timestamp + "." + rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(given);
  return a.length === b.length && timingSafeEqual(a, b);
}

export async function POST(req: Request) {
  const raw = await req.text(); // the exact bytes that were signed
  const ok = verify(SECRET, req.headers.get("x-zmle-timestamp") ?? "", raw, req.headers.get("x-zmle-signature") ?? "");
  if (!ok) return new Response("invalid signature", { status: 401 });

  const delivery = JSON.parse(raw) as { id: string; event: string; createdAt: string; data: Record<string, unknown> };
  // queue the work and answer fast (within 10 s)
  console.log("zmle event", delivery.event, delivery.id);
  return Response.json({ ok: true });
}
Express: keep the raw body
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
app.post("/hooks/zmle", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  const ts = req.get("x-zmle-timestamp") ?? "";
  const given = req.get("x-zmle-signature") ?? "";
  const expected = "sha256=" + createHmac("sha256", process.env.ZMLE_WEBHOOK_SECRET).update(ts + "." + raw).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  const same = expected.length === given.length && timingSafeEqual(Buffer.from(expected), Buffer.from(given));
  if (!fresh || !same) return res.status(401).send("invalid signature");
  res.sendStatus(204);
});
app.listen(3000);
Never compare signatures with ===: use timingSafeEqual on equal-length buffers. And never log the secret.

Marketplace install and uninstall calls

An integration's installUrl and uninstallUrl receive calls signed the same way, but with your listing's app secret (mksec_…, in the developer portal after the first approval, rotatable) and the headers X-Zmle-Timestamp / X-Zmle-Signature. Webhooks that follow are signed with the endpoint's whsec_… secret from the install call.

examples/marketplace/integration-hello-sync/receiver.mjs (verify)
function verify(req, raw) {
  const ts = req.headers["x-zmle-timestamp"];
  const sig = String(req.headers["x-zmle-signature"] ?? "");
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window: 5 minutes
  const want = `sha256=${createHmac("sha256", SECRET).update(`${ts}.${raw}`).digest("hex")}`;
  return want.length === sig.length && timingSafeEqual(Buffer.from(want), Buffer.from(sig));
}

Written from: docs/API.md, src/lib/integrations/signing.ts, src/lib/integrations/webhooks.ts, docs/DEVELOPERS/INTEGRATION-SPEC.md, examples/marketplace/integration-hello-sync/receiver.mjs, src/lib/marketplace/install.ts