> ## Documentation Index
> Fetch the complete documentation index at: https://developers.qsmarthub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segurança dos webhooks: assinatura e replay

> Valide a assinatura HMAC-SHA256 de cada webhook do QSmartHub, proteja-se contra replay e conheça os requisitos do seu endpoint.

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:

| Cabeçalho | Exemplo | Para que serve |
| - | - | - |
| `X-QSmartHub-Event` | `call.called` | O tipo do evento |
| `X-QSmartHub-Delivery` | `evt_01JQ8Z...` | O `id` único da entrega (use para idempotência) |
| `X-QSmartHub-Timestamp` | `1793374200` | O horário (Unix) em que foi assinado |
| `X-QSmartHub-Signature` | `sha256=<hex>` | A assinatura HMAC |

## 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:

```
X-QSmartHub-Signature = "sha256=" + HMAC_SHA256(segredo, timestamp + "." + corpo_bruto)
```

O `timestamp` entra na mensagem assinada de propósito: reusar o mesmo corpo com outro horário quebra a assinatura, o que impede replay.

> [!WARNING]
>
> 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.

```javascript Node.js (Express) theme={null}
const crypto = require("crypto");

function webhookValido(req, segredo) {
  const assinatura = req.header("X-QSmartHub-Signature") || "";
  const timestamp  = req.header("X-QSmartHub-Timestamp") || "";
  const corpoBruto = req.rawBody; // os bytes crus, não o objeto já parseado

  // 1. Rejeite entregas com mais de 5 minutos (tolerância de replay)
  const idade = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!timestamp || idade > 300) return false;

  // 2. Recalcule a assinatura sobre \"timestamp.corpo\"
  const esperada = "sha256=" + crypto
    .createHmac("sha256", segredo)
    .update(timestamp + "." + corpoBruto)
    .digest("hex");

  // 3. Compare em tempo constante (comprimentos iguais primeiro)
  if (assinatura.length !== esperada.length) return false;
  return crypto.timingSafeEqual(Buffer.from(assinatura), Buffer.from(esperada));
}
```

```php PHP theme={null}
$assinatura = $_SERVER["HTTP_X_QSMARTHUB_SIGNATURE"] ?? "";
$timestamp  = $_SERVER["HTTP_X_QSMARTHUB_TIMESTAMP"] ?? "";
$corpoBruto = file_get_contents("php://input");

// 1. Rejeite entregas com mais de 5 minutos
if ($timestamp === "" || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit;
}

// 2. Recalcule e 3. compare em tempo constante
$esperada = "sha256=" . hash_hmac("sha256", $timestamp . "." . $corpoBruto, $segredo);

if (! hash_equals($esperada, $assinatura)) {
    http_response_code(400);
    exit;
}
```

## 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).

> [!TIP]
>
> 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**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.