Assinatura de Webhook (HMAC-SHA256)

Valide a autenticidade e integridade das notificações recebidas da Barte usando HMAC-SHA256.

O que é e por que usar

A Barte já opera com IP de saída fixo nas entregas de webhook, permitindo que você configure um allowlist de IPs no firewall como primeira camada de verificação.

A assinatura de webhook é uma camada complementar, que opera no nível da aplicação e resolve dois problemas que o IP fixo não endereça:

• Integridade do payload: garante que o conteúdo da notificação não foi alterado em trânsito.

• Autenticidade verificável em qualquer ambiente: funciona em ambientes serverless e sem controle de firewall.

A assinatura de webhook é opcional e retrocompatível. Quem não configurar um secret continua recebendo webhooks normalmente, sem nenhuma quebra.

---

Como funciona

Quando você configura um secret no webhook, a Barte passa a:

1. Montar um payload canônico concatenando timestamp, nonce e corpo da requisição.

2. Calcular HMAC-SHA256(secret, payload_canônico) antes de cada entrega.

3. Incluir o resultado no header X-Webhook-Signature: sha256=<hex>.

Do seu lado, você monta o mesmo payload canônico, recalcula o HMAC com o seu secret e compara com o header recebido. Se baterem, a notificação é autêntica e o payload não foi alterado.

Payload canônico

{timestamp}.{nonce}.{body}

Campo	Origem
timestamp	Valor exato do header X-Webhook-Timestamp
nonce	Valor exato do header X-Webhook-Nonce
body	Corpo bruto da requisição (raw JSON, sem reformatação)

Os três campos são concatenados com . como separador.

Algoritmo

signature = "sha256=" + hex(HMAC_SHA256(secret, "{timestamp}.{nonce}.{body}"))

A assinatura é sempre em hexadecimal minúsculo, prefixada com sha256=.

O nonce e o timestamp são incluídos na assinatura para mitigar replay attacks — um payload interceptado não pode ser reusado porque o timestamp estará fora da janela de tolerância.

---

Novos headers

Quando a assinatura está habilitada, a Barte inclui três novos headers na entrega:

Header	Exemplo	Descrição
X-Webhook-Timestamp	1789046804	Unix timestamp (segundos) do momento da entrega
X-Webhook-Nonce	228bb8a88c43c8655145ea2aaaf2ae60	Valor aleatório único por entrega, usado para prevenir replay attacks
X-Webhook-Signature	sha256=a28acabd32c79bdcb219dfd50396d97df4b1119e8c0b4fcd671f13b0ae118ac7	Assinatura HMAC-SHA256 do payload canônico

---

Como configurar o secret

O secret é definido apenas no momento da criação do webhook. Não é possível gerar ou visualizar o secret em edições posteriores.

1. Acesse o painel da Barte e vá em Configurações → Integração.

2. Clique em Novo Webhook.

3. No campo de secret, escolha uma das opções:

   • Geração automática: ative o toggle de geração automática e a Barte criará um secret seguro para você.

   • Secret próprio: informe um valor de sua escolha com entre 32 e 64 caracteres.

4. Clique em Salvar e copie o secret exibido.

O secret é exibido apenas uma vez, no momento da criação. Salve-o imediatamente em um local seguro — não será possível recuperá-lo depois. Se perder o secret, será necessário cadastrar um novo webhook para obter um novo valor.

---

Como verificar a assinatura

Ao receber uma notificação, siga os passos:

1. Leia os headers X-Webhook-Timestamp, X-Webhook-Nonce e X-Webhook-Signature.

2. Capture o corpo bruto da requisição — sem fazer parse nem reserializar o JSON. Qualquer alteração de espaços ou ordem de chaves invalida a assinatura.

3. Monte a string "{timestamp}.{nonce}.{body}" e calcule o HMAC-SHA256 com o seu secret.

4. Compare o resultado com X-Webhook-Signature usando comparação em tempo constante.

5. Recomendado: valide que o X-Webhook-Timestamp está dentro de uma janela de tolerância (ex.: ±5 minutos) para mitigar replay attacks. Opcionalmente, controle os nonces já processados para rejeitar reenvios idênticos.

Sempre use comparação em tempo constante — hmac.compare_digest no Python, crypto.timingSafeEqual no Node.js, hash_equals no PHP, MessageDigest.isEqual no Java. Comparação simples com == é vulnerável a timing attacks.

---

Como rotacionar o secret

Caso precise trocar o secret de um webhook (por exemplo, se o valor anterior foi comprometido), siga o fluxo abaixo:

1. Cadastre um segundo webhook com a mesma URL e o secret novo.

2. Atualize seu sistema para aceitar assinaturas geradas com o secret novo.

3. Valide que as entregas estão chegando e sendo verificadas corretamente.

4. Delete o webhook antigo após confirmar que tudo está funcionando.

Não exclua o webhook antigo antes de validar o novo — você pode perder entregas durante a transição.

---

Perguntas frequentes

Preciso implementar o signing? Não. É opcional. Se você não configurar um secret, os webhooks continuam sendo entregues normalmente, sem o header X-Webhook-Signature.

O que acontece se eu não verificar a assinatura? Os eventos são entregues normalmente. A verificação é uma proteção do seu lado — sem ela, seu sistema não tem como distinguir uma notificação legítima da Barte de uma requisição forjada.

Como testar em sandbox? Configure um webhook no ambiente de sandbox com qualquer secret de sua escolha e dispare um evento de teste. Verifique se o header X-Webhook-Signature chega e se o HMAC calculado bate com o valor recebido.

O secret aparece em algum endpoint GET? Parcialmente. A API retorna um preview com os 5 primeiros caracteres do secret, permitindo identificar qual valor foi configurado. O secret completo nunca é retornado após a criação.