#Assinatura e segurança
Qualquer pessoa que descubra a sua URL pode mandar um POST falso para ela. A assinatura é a prova de que o aviso é nosso e de que não foi alterado no caminho. Confira sempre, antes de fazer qualquer coisa com o conteúdo.
Usamos o padrão público Standard Webhooks (HMAC-SHA256). Se você já usou Svix, Clerk ou outros que seguem o padrão, o código é o mesmo.
#Os três cabeçalhos assinados
| Cabeçalho | O que traz |
|---|---|
webhook-id | Identificador único do aviso. É também a chave de idempotência (veja Entrega). |
webhook-timestamp | Momento do envio, em segundos desde 1970 (Unix). |
webhook-signature | v1,<assinatura em base64>. Pode trazer mais de uma, separadas por espaço. |
#Como a assinatura é calculada
- Monte o texto:
webhook-id+.+webhook-timestamp+.+ corpo cru. - Calcule o HMAC-SHA256 desse texto com a chave.
- Converta o resultado para base64 e compare com a parte depois de
v1,.
A chave é o segredo whsec_..., mas com um detalhe que derruba muita gente: depois de tirar o prefixo whsec_, o que sobra é base64, e o HMAC usa os bytes que esse base64 representa, não o texto dele.
#Corpo cru: a armadilha número 1
A assinatura é feita sobre os bytes exatos que enviamos. Se o seu framework converte o JSON em objeto e você depois converte de volta para texto, o espaçamento e a ordem das chaves podem mudar e a assinatura nunca vai bater. Leia o corpo cru antes de qualquer conversão:
- Express:
express.raw({ type: "application/json" }); - PHP:
file_get_contents('php://input'); - Flask/FastAPI:
request.get_data()/await request.body().
#Tolerância de tempo (5 minutos)
Rejeite avisos cujo webhook-timestamp esteja a mais de 5 minutos de agora (para o passado ou o futuro). Isso impede que alguém grave um aviso legítimo e o reenvie semanas depois. Seu relógio precisa estar correto (NTP ligado).
Atenção: uma nova tentativa (retry) é assinada de novo, com timestamp novo. Então um aviso reenviado horas depois passa na checagem de tempo sem problema.
#Código pronto
Os três códigos abaixo fazem a mesma coisa e não usam nenhuma biblioteca externa. Escolha a sua linguagem.
// Confere a assinatura de um webhook do Business OS (Standard Webhooks). Só biblioteca padrão do Node, sem dependência.
// `rawBody` tem de ser o corpo CRU (Buffer ou string), exatamente como chegou. NÃO use o objeto que o framework já converteu.
const crypto = require("node:crypto");function verifyWebhook(secret, rawBody, headers, toleranceSeconds = 300) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) throw new Error("faltam cabeçalhos de assinatura");
// 1. O aviso não pode ser velho nem do futuro (protege contra quem grava e reenvia uma mensagem antiga).
const diff = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(diff) || diff > toleranceSeconds) throw new Error("timestamp fora da tolerância");
// 2. O segredo é "whsec_" + base64. O HMAC usa os BYTES que o base64 representa, não o texto.
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
// 3. Texto assinado: "<webhook-id>.<webhook-timestamp>.<corpo cru>".
const signed = Buffer.concat([Buffer.from(${id}.${timestamp}.), Buffer.from(rawBody)]);
const expected = crypto.createHmac("sha256", key).update(signed).digest();
// 4. O cabeçalho pode trazer mais de uma assinatura ("v1,xxx v1,yyy"): basta uma bater.
for (const part of String(signatures).split(" ")) {
const [version, sig] = part.split(",");
if (version !== "v1" || !sig) continue;
const got = Buffer.from(sig, "base64");
if (got.length === expected.length && crypto.timingSafeEqual(got, expected)) return true;
}
throw new Error("assinatura inválida");
}
module.exports = { verifyWebhook };
baixar verify.js<?php
// Confere a assinatura de um webhook do Business OS (Standard Webhooks). Só funções nativas do PHP, sem dependência.
// $rawBody tem de ser o corpo CRU: file_get_contents('php://input'). NÃO use json_decode antes de conferir.
// $headers: use getallheaders() (nomes originais). $_SERVER não serve: lá o cabeçalho vira HTTP_WEBHOOK_ID.
function verify_webhook(string $secret, string $rawBody, array $headers, int $tolerance = 300): void
{
$h = array_change_key_case($headers, CASE_LOWER);
$id = $h['webhook-id'] ?? null;
$timestamp = $h['webhook-timestamp'] ?? null;
$signatures = $h['webhook-signature'] ?? null;
if (!$id || !$timestamp || !$signatures) {
throw new RuntimeException('faltam cabeçalhos de assinatura');
}
// 1. O aviso não pode ser velho nem do futuro.
if (!ctype_digit((string) $timestamp) || abs(time() - (int) $timestamp) > $tolerance) {
throw new RuntimeException('timestamp fora da tolerância');
}
// 2. O segredo é "whsec_" + base64. O HMAC usa os BYTES que o base64 representa, não o texto.
$key = base64_decode(preg_replace('/^whsec_/', '', $secret), true);
// 3. Texto assinado: "<webhook-id>.<webhook-timestamp>.<corpo cru>".
$expected = base64_encode(hash_hmac('sha256', $id . '.' . $timestamp . '.' . $rawBody, $key, true));
// 4. O cabeçalho pode trazer mais de uma assinatura ("v1,xxx v1,yyy"): basta uma bater.
foreach (explode(' ', $signatures) as $part) {
[$version, $sig] = array_pad(explode(',', $part, 2), 2, '');
if ($version === 'v1' && $sig !== '' && hash_equals($expected, $sig)) {
return;
}
}
throw new RuntimeException('assinatura inválida');
}
baixar verify.php# Confere a assinatura de um webhook do Business OS (Standard Webhooks). Só biblioteca padrão do Python, sem dependência.
#raw_body tem de ser o corpo CRU em bytes, exatamente como chegou. NÃO use o JSON que o framework já converteu.
import base64
import hashlib
import hmac
import time
class InvalidSignature(Exception):
pass
def verify_webhook(secret: str, raw_body: bytes, headers: dict, tolerance_seconds: int = 300) -> bool:
h = {k.lower(): v for k, v in headers.items()}
msg_id = h.get("webhook-id")
timestamp = h.get("webhook-timestamp")
signatures = h.get("webhook-signature")
if not msg_id or not timestamp or not signatures:
raise InvalidSignature("faltam cabeçalhos de assinatura")
# 1. O aviso não pode ser velho nem do futuro.
try:
diff = abs(time.time() - int(timestamp))
except ValueError:
raise InvalidSignature("timestamp inválido")
if diff > tolerance_seconds:
raise InvalidSignature("timestamp fora da tolerância")
# 2. O segredo é "whsec_" + base64. O HMAC usa os BYTES que o base64 representa, não o texto.
key = base64.b64decode(secret.removeprefix("whsec_"))
# 3. Texto assinado: "<webhook-id>.<webhook-timestamp>.<corpo cru>".
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
# 4. O cabeçalho pode trazer mais de uma assinatura ("v1,xxx v1,yyy"): basta uma bater.
for part in signatures.split(" "):
version, _, sig = part.partition(",")
if version == "v1" and sig and hmac.compare_digest(sig, expected):
return True
raise InvalidSignature("assinatura inválida")
baixar verify.py#PHP: leia os cabeçalhos com getallheaders()
$headers = getallheaders(); // nomes como chegaram: "webhook-id", "webhook-timestamp"...
$rawBody = file_get_contents('php://input'); // corpo cru, antes de qualquer json_decode
verify_webhook(getenv('KB_WEBHOOK_SECRET'), $rawBody, $headers);
Não use $_SERVER para isso: o PHP renomeia webhook-id para HTTP_WEBHOOK_ID (maiúsculas, _ no lugar de -, prefixo HTTP_) e a função não o encontraria. Use getallheaders(); a função verify_webhook converte os nomes para minúscula antes de procurar.
#Como testar o seu código
Gere uma assinatura com o próprio segredo de teste e confira se o seu código aceita. Nós rodamos esse mesmo teste contra o código de assinatura do servidor (os exemplos de Node e Python deste site são executados em teste automático contra a implementação real). O PHP segue o mesmo algoritmo e também foi executado (PHP 8.3), com o mesmo resultado.
Valores de verificação úteis:
- troque um único caractere do corpo: tem de falhar;
- troque o
webhook-id: tem de falhar; - use um timestamp de 10 minutos atrás: tem de falhar;
- chave errada: tem de falhar.
#Mais segurança, do seu lado
- Guarde o segredo em variável de ambiente ou cofre. Nunca no repositório.
- Use sempre https. Nós só enviamos para URLs https e não seguimos redirecionamento.
- Compare assinaturas com função de tempo constante (
timingSafeEqual,hmac.compare_digest,hash_equals), como nos exemplos. - Responda
4xxpara assinatura inválida e não processe o conteúdo. - Se o segredo vazar, peça um novo à equipe do Business OS. Enquanto isso, o segredo antigo deve ser considerado comprometido.
#Cabeçalhos extras (não assinados)
Além dos três acima, mandamos cabeçalhos informativos. Eles não fazem parte da assinatura: não decida nada de segurança com base neles.
| Cabeçalho | Significado |
|---|---|
x-kb-attempt | Número da tentativa (1, 2, 3...). |
x-kb-attempt-id | Identificador desta tentativa específica. |
x-kb-delivery-kind | Por que este envio aconteceu: first, auto_retry, manual_redelivery, period_redelivery ou manual_test. |
x-kb-sale-key | Chave da venda (liga todos os avisos da mesma venda). |
x-kb-fact-key | Chave do fato (identifica o acontecimento). |
x-kb-first-sent-at | Quando o primeiro envio saiu. Só aparece do 2º envio em diante. |
x-kb-source-provider | Plataforma de origem. Nos eventos access.* vem sempre com o valor kb. |
x-kb-source-delivery-id | Id do aviso na plataforma de origem (não vem nos eventos access.*). |
Também enviamos content-type: application/json e user-agent: kbtec-gateway/1.