Business OS · Documentação

#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çalhoO que traz
webhook-idIdentificador único do aviso. É também a chave de idempotência (veja Entrega).
webhook-timestampMomento do envio, em segundos desde 1970 (Unix).
webhook-signaturev1,<assinatura em base64>. Pode trazer mais de uma, separadas por espaço.

#Como a assinatura é calculada

  1. Monte o texto: webhook-id + . + webhook-timestamp + . + corpo cru.
  2. Calcule o HMAC-SHA256 desse texto com a chave.
  3. 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:

#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) &gt; $tolerance) {
    throw new RuntimeException('timestamp fora da tolerância');
}

// 2. O segredo é &quot;whsec_&quot; + 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: &quot;&lt;webhook-id&gt;.&lt;webhook-timestamp&gt;.&lt;corpo cru&gt;&quot;.
$expected = base64_encode(hash_hmac('sha256', $id . '.' . $timestamp . '.' . $rawBody, $key, true));

// 4. O cabeçalho pode trazer mais de uma assinatura (&quot;v1,xxx v1,yyy&quot;): basta uma bater.
foreach (explode(' ', $signatures) as $part) {
    [$version, $sig] = array_pad(explode(',', $part, 2), 2, '');
    if ($version === 'v1' &amp;&amp; $sig !== '' &amp;&amp; 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(&quot;timestamp inválido&quot;)
if diff &gt; tolerance_seconds:
    raise InvalidSignature(&quot;timestamp fora da tolerância&quot;)

# 2. O segredo é &quot;whsec_&quot; + base64. O HMAC usa os BYTES que o base64 representa, não o texto.
key = base64.b64decode(secret.removeprefix(&quot;whsec_&quot;))

# 3. Texto assinado: &quot;&lt;webhook-id&gt;.&lt;webhook-timestamp&gt;.&lt;corpo cru&gt;&quot;.
signed = f&quot;{msg_id}.{timestamp}.&quot;.encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

# 4. O cabeçalho pode trazer mais de uma assinatura (&quot;v1,xxx v1,yyy&quot;): basta uma bater.
for part in signatures.split(&quot; &quot;):
    version, _, sig = part.partition(&quot;,&quot;)
    if version == &quot;v1&quot; and sig and hmac.compare_digest(sig, expected):
        return True
raise InvalidSignature(&quot;assinatura inválida&quot;)

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:

#Mais segurança, do seu lado

#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çalhoSignificado
x-kb-attemptNúmero da tentativa (1, 2, 3...).
x-kb-attempt-idIdentificador desta tentativa específica.
x-kb-delivery-kindPor que este envio aconteceu: first, auto_retry, manual_redelivery, period_redelivery ou manual_test.
x-kb-sale-keyChave da venda (liga todos os avisos da mesma venda).
x-kb-fact-keyChave do fato (identifica o acontecimento).
x-kb-first-sent-atQuando o primeiro envio saiu. Só aparece do 2º envio em diante.
x-kb-source-providerPlataforma de origem. Nos eventos access.* vem sempre com o valor kb.
x-kb-source-delivery-idId 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.


← Início rápido  ·  Entrega, retries e idempotência →