Guia de integração
Verificando a assinatura dos webhooks
Valide a autenticidade dos webhooks da Zypfy com HMAC-SHA256 (X-Webhook-Signature + X-Webhook-Timestamp).
Todo webhook que a Zypfy envia ao seu sistema é assinado. Use a assinatura para garantir que a notificação veio mesmo da Zypfy e não foi adulterada.
Headers enviados
| Header | Descrição |
|---|---|
X-Webhook-Signature | HMAC-SHA256, em hex, do corpo da requisição. |
X-Webhook-Timestamp | Unix time (em segundos) de quando o webhook foi assinado. |
Como a assinatura é calculada
assinatura = HMAC_SHA256(secret, `${X-Webhook-Timestamp}.${corpo_bruto}`)secreté a sua Webhook Signature, disponível no painel em Configurações > Credenciais. Você pode gerar/rotacionar essa chave por lá.corpo_brutoé o corpo HTTP exatamente como recebido (raw body). Não re-serialize o JSON antes de calcular o HMAC — isso muda os bytes e a verificação falha.- A assinatura é o digest em hexadecimal minúsculo.
Passos recomendados
- Leia o corpo bruto da requisição (sem fazer parse/round-trip do JSON).
- Leia os headers
X-Webhook-SignatureeX-Webhook-Timestamp. - Rejeite se o timestamp estiver a mais de 5 minutos do horário atual (proteção contra replay).
- Recompute o HMAC e compare com
X-Webhook-Signatureusando comparação timing-safe.
Exemplo — Node.js (Express)
const crypto = require('crypto');
// Capture o corpo BRUTO (ex.: express.raw) para não re-serializar o JSON.
app.post('/webhooks/zypfy', express.raw({ type: 'application/json' }), (req, res) => {
const secret = process.env.ZYPFY_WEBHOOK_SECRET;
const signature = req.header('X-Webhook-Signature') || '';
const timestamp = req.header('X-Webhook-Timestamp') || '';
// Anti-replay: 5 minutos.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.status(401).json({ error: 'timestamp expirado' });
}
const rawBody = req.body.toString('utf8');
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
const a = Buffer.from(signature, 'hex');
const b = Buffer.from(expected, 'hex');
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).json({ error: 'assinatura invalida' });
}
const evento = JSON.parse(rawBody);
// ... processa o evento ...
return res.json({ ok: true });
});Exemplo — PHP
<?php
$secret = getenv('ZYPFY_WEBHOOK_SECRET');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$rawBody = file_get_contents('php://input');
// Anti-replay: 5 minutos.
if (abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit('timestamp expirado');
}
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('assinatura invalida');
}
$evento = json_decode($rawBody, true);
// ... processa o evento ...
http_response_code(200);
echo json_encode(['ok' => true]);Notas
- Se você ainda não tem uma Webhook Signature, gere uma em Configurações > Credenciais. Contas novas já nascem com uma chave.
- Ao rotacionar a chave, atualize o
secretno seu sistema. Webhooks enviados após a rotação usam a nova chave.