Skip to main content
Todo webhook do QSmartHub é assinado. Valide a assinatura antes de confiar no corpo: é ela que garante que o evento veio do QSmartHub e não foi adulterado no caminho. Esta página mostra como.

Os cabeçalhos

Cada entrega traz quatro cabeçalhos:

Como a assinatura é montada

A assinatura é um HMAC-SHA256, com o segredo do endpoint como chave, sobre a string timestamp + . + corpo bruto da requisição:
O timestamp entra na mensagem assinada de propósito: reusar o mesmo corpo com outro horário quebra a assinatura, o que impede replay.
Assine e compare sobre o corpo bruto (os bytes exatos recebidos), nunca sobre o JSON re-serializado. Reconstruir o JSON muda espaços e ordem de chaves e invalida a assinatura. Guarde o corpo cru antes de fazer o parse.

Validar a entrega

Três passos: rejeite entregas antigas, recalcule a assinatura e compare em tempo constante.

Proteja-se contra replay e duplicatas

  • Janela de tempo. Recuse entregas cujo X-QSmartHub-Timestamp esteja a mais de 300 segundos do seu relógio. A assinatura cobre o timestamp, então ele não pode ser forjado.
  • Idempotência. Guarde os X-QSmartHub-Delivery (o id evt_...) já processados e ignore repetições. A entrega é pelo menos uma vez, então o mesmo evento pode chegar de novo.

Requisitos do seu endpoint

O QSmartHub só entrega para endereços que ele consegue alcançar com segurança:
  • HTTPS obrigatório, em host público (portas 80 ou 443).
  • Endereços privados, loopback e de rede local são recusados, tanto no cadastro quanto a cada entrega (proteção contra SSRF).
Guarde o segredo do endpoint num cofre de segredos, nunca em código versionado. Se ele vazar, rotacione o segredo pelo painel, em Integrações › Webhooks.