Cuidado na hora de combinar middlewares no Node.js

Quando você pensa em receber payloads diferentes na mesma rota, a primeira reação costuma ser usar express.json() para JSON e, às vezes, express.raw() para payloads específicos, como webhooks do Stripe.

Porém, a prática de usar esses middlewares juntos pode gerar dor de cabeça. Se você não pensar na ordem ou na configuração, o servidor pode simplesmente não receber o webhook, como aconteceu nesse caso. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

O segredo está na ordem de aplicação. No exemplo do StackOverflow, o middleware raw precisa vir antes do json, porque o Stripe envia payloads brutos para o webhook e, se o json for processado primeiro, o payload vira um objeto e o Stripe não consegue validar a assinatura. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Na sua aplicação, o ideal é definir rotas específicas para webhooks, usando express.raw() só nelas, e fazer o resto usando express.json(). Assim, evita-se confusão e problemas de processamento de payloads. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois.

No seu time, já passou por isso? Como vocês lidam com diferentes tipos de payload na mesma API?