Assinatura e payloads
O envelope do payload
Toda entrega compartilha o mesmo envelope. O objeto data é moldado pelo tipo de evento.
{
"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 fica fixado no seu endpoint no momento da criação (atualmente 2026-06-01) — uma futura alteração incompatível na estrutura de data afeta apenas endpoints criados após essa mudança de versão.
Request headers
Cada entrega inclui estes cabeçalhos junto com o corpo assinado:
Synup-SignatureA assinatura a ser verificada — veja abaixo.Synup-DeliveryO id próprio do envelope. Útil para deduplicar uma entrega reenviada.Synup-EventO tipo de evento do envelope — permite rotear sem analisar o corpo primeiro.Verificando assinaturas
Toda requisição carrega um cabeçalho Synup-Signature para que você possa confirmar que ela realmente veio do Synup:
Synup-Signature: t=1788112324,v1=8f4c...a91dRecalcule o HMAC-SHA256 sobre t + "." + rawBody usando a chave de assinatura do seu endpoint, e compare com v1 em tempo constante. Rejeite qualquer assinatura em que t tenha mais de cinco minutos, para limitar a exposição a ataques de repetição.
A verificação precisa dos bytes brutos exatos da requisição. Se o analisador de corpo do seu framework rodar primeiro e reserializar o JSON — mesmo que só reformatando espaços —, a assinatura não vai corresponder. Leia o corpo bruto dessa rota antes que qualquer middleware de análise de JSON o toque.
Exemplo
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 });
});Teste sua implementação
Execute seu verificador com estes valores fixos — se sua saída corresponder à assinatura esperada abaixo, sua implementação está correta.
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}}Assinatura esperadat=1700000000,v1=6204bc359e5eabdf2060a37634581c0276a9c99221d54a6063cb4373f43b2b04Playground de assinatura
Calcula o HMAC inteiramente no seu navegador — nada aqui é enviado a lugar nenhum. Cole sua própria chave e payload para ver o cabeçalho exato que enviaríamos.