Signing & payloads
The payload envelope
Every delivery shares the same envelope. The data object is shaped by the event type.
{
"id": "msg_3Ge4EysPsTMIbms5w4bM45ZkR5z",
"type": "review.received",
"created_at": "2026-08-30T14:12:04Z",
"api_version": "2026-06-01",
"data": {
"review_id": "rev_8kQ2mT",
"location_id": "loc_4419",
"client_id": "cli_221",
"directory": "google",
"rating": 2,
"author": "M. Ferraro",
"text": "Waited 40 minutes past my appointment.",
"language": "en",
"url": "https://maps.google.com/.../rev_8kQ2mT"
}
}api_version is pinned to your endpoint at creation time (currently 2026-06-01) — a future breaking change to a payload's data shape only affects endpoints created after that version bumps.
Request headers
Every delivery includes these headers alongside the signed body:
Synup-SignatureThe signature to verify — see below.Synup-DeliveryThe envelope's own id. Useful for de-duplicating a retried delivery.Synup-EventThe envelope's event type — lets you route without parsing the body first.Verifying signatures
Every request carries a Synup-Signature header so you can confirm it actually came from Synup:
Synup-Signature: t=1788112324,v1=8f4c...a91dRecompute HMAC-SHA256 over t + "." + rawBody using your endpoint's signing secret, and compare it to v1 in constant time. Reject anything where t is more than five minutes old, to bound replay-attack exposure.
Verification needs the exact raw request bytes. If your framework's body parser runs first and re-serializes JSON — even just reformatting whitespace — the signature won't match. Read the raw body for this route before any JSON-parsing middleware touches it.
Example
const crypto = require("crypto");
function verifyWebhookSignature(header, rawBody, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
const t = Number(parts.t);
const v1 = parts.v1;
if (!t || !v1) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const signedPayload = `${t}.${rawBody}`;
const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
const a = Buffer.from(v1, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
}
// Express example
app.post("/synup/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.header("Synup-Signature");
if (!verifyWebhookSignature(signature, req.body.toString("utf8"), process.env.SYNUP_WEBHOOK_SECRET)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body);
// ... handle event.type / event.data
res.status(200).send({ received: true });
});Test your implementation
Run your verifier against these fixed values — if your output matches the expected signature below, your implementation is correct.
whsec_test_secret_keyTimestamp1700000000Payload{"id":"evt_test123","type":"review.received","created_at":"2023-11-14T22:13:20Z","api_version":"2026-06-01","data":{"review_id":"rev_test","rating":5}}Expected signaturet=1700000000,v1=6204bc359e5eabdf2060a37634581c0276a9c99221d54a6063cb4373f43b2b04Signature playground
Computes the HMAC entirely in your browser — nothing here is sent anywhere. Paste your own secret and payload to see the exact header we'd send.