Como a xFlow assina os webhooks
A cada evento, a xFlow envia um POST JSON para a URL cadastrada com os headers x-webhook-event e x-webhook-signature: sha256=<HMAC-SHA256 do corpo cru, com o segredo do endpoint>. O segredo aparece uma única vez, quando o endpoint é criado. A entrega é repetida até 3 vezes; responda 2xx para confirmar. Os detalhes estão em webhook Pix e na documentação.
Passo a passo no seu servidor
- Leia o corpo cru da requisição, antes de qualquer parse de JSON.
- Calcule o HMAC-SHA256 desse corpo com o segredo do endpoint.
- Compare com o valor do header em tempo constante.
- Só então processe o evento e responda
2xx.
Exemplos prontos em Node.js, PHP, Python e nos arquivos de exemplo.
Perguntas frequentes
Por que a assinatura não bate no meu servidor?
Quase sempre o corpo foi alterado antes da validação: o framework leu e transformou o JSON, reordenou campos ou mudou espaços. Valide sobre o corpo cru, byte a byte, antes de fazer o parse.
O segredo é enviado para algum lugar?
Não. O cálculo usa a Web Crypto do seu navegador, nesta página. Mesmo assim, prefira testar com o segredo de um endpoint de teste.
Como comparar a assinatura no código?
Calcule o HMAC-SHA256 do corpo cru com o segredo do endpoint e compare com o header usando uma comparação de tempo constante, como crypto.timingSafeEqual no Node.js ou hash_equals no PHP.