Seguranca de Webhooks

Verificacao HMAC-SHA256

Toda entrega de webhook inclui o header X-Zemo-Signature com a assinatura HMAC-SHA256 do body.

Verificacao em Python

import hmac
import hashlib

def verify_webhook(body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# No seu endpoint:
body = request.body()
signature = request.headers["X-Zemo-Signature"]
if not verify_webhook(body, WEBHOOK_SECRET, signature):
    return Response(status_code=401)

Verificacao em Node.js

const crypto = require('crypto');

function verifyWebhook(body, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Headers enviados

Header	Descricao
X-Zemo-Signature	HMAC-SHA256 do body
X-Zemo-Event-Type	Tipo do evento (ex: operation.paid)
X-Zemo-Event-Id	UUID unico do evento
X-Zemo-Timestamp	ISO 8601 UTC do envio

Boas praticas

1. Sempre verifique a assinatura antes de processar
2. Responda com 2xx rapidamente — aguardamos no máximo 10 s (timeout de entrega); idealmente responda em < 5 s e processe de forma assíncrona
3. Seja idempotente — o mesmo evento pode ser entregue mais de uma vez
4. Use HTTPS — webhooks so sao enviados para URLs HTTPS
5. Monitore entregas via GET /v1/webhooks/{id}/deliveries