La integració de webhooks de Square és una pràctica habitual en moltes plataformes que processen pagaments o gestionen subscripcions. No obstant això, validar la signatura d'aquests webhooks amaga un detall que sol passar desapercebut i que provoca fallades difícils de depurar: la URL de notificació forma part del missatge signat. Si no es replica exactament com Square la té registrada, cada notificació fallarà la verificació, fins i tot quan el codi HMAC sembli correcte. Entendre aquest mecanisme a fons és clau per garantir que les transaccions es processin sense pèrdues ni retards.
Square utilitza HMAC-SHA256 per signar els seus webhooks. El valor de l'encapçalat x-square-hmacsha256-signature es calcula concatenant la URL de notificació configurada en el panell de Square amb el cos sense processar de la sol·licitud (raw body), aplicant després l'algoritme HMAC amb la clau de signatura associada a aquesta subscripció i codificant el resultat en base. Això significa que qualsevol discrepància a la URL, ja sigui un protocol diferent, un canvi de host, una barra final o un path lleugerament diferent, farà que la firma no coincideixi. A més, el cos ha de ser exactament el que Square va enviar, sense parsear-lo ni re-serialitzar-lo, perquè els espais, l'ordre de les claus o el format dels números alteren el resultat.
Un dels errors més comuns és reconstruir la URL a partir de les capçaleres de la petició (req.protocol, req.headers.host). Un proxy invers o un balancejador de càrrega que acabi TLS pot retornar HTTP en lloc d' HTTPS, o un nom de host diferent al registrat. La solució més segura és tractar la URL com una constant per entorn, exactament la que es va configurar a Square. Un altre error freqüent és verificar contra un cos re-serialitzat després de parsear JSON; la firma espera els bytes originals, no una representació reconstruïda.
La seguretat no acaba en la comparació de firmes. És fonamental usar una funció de comparació en temps constant, com crypto.timingSafeEqual, per evitar atacs de temporització que permetin deduir la firma correcta byte a byte. A més, Square està retirant l'encapçalat legacy x-square-signature (basat en SHA1) a favor de l'actual SHA256. Mantenir codi antic exposa la integració a vulnerabilitats i a fallades de compatibilitat.
Des d'una perspectiva empresarial, una validació incorrecta de webhooks pot traduir-se en notificacions perdudes sobre pagaments completats, reemborsaments o disputes. Square reintenta les entregues fallides durant un temps limitat; si el servidor no respon correctament, la subscripció es pot desactivar. Això representa un risc directe per a la continuïtat del negoci. Per això, comptar amb una infraestructura robusta que capturi el cos en cru, verifiqui la firma de forma constant i gestioni reintents és crític.
En Q2BSTUDIO som especialistes en ciberseguretat i desenvolupament de programari segur. Ajudem empreses a implementar validacions de webhook que resisteixin aquests escenaris, combinant bones pràctiques de seguretat amb serveis cloud com AWS i Azure per garantir alta disponibilitat. El nostre equip també integra intel·ligència artificial per a empreses i agents IA que automatitzen la resposta a esdeveniments, així com solucions d'intel·ligència de negoci amb Power BI per monitoritzar el flux de transaccions en temps real. Ja sigui que necessitis aplicacions a mida per manejar webhooks o una plataforma completa de notificacions, el nostre enfocament multidisciplinari assegura que cada esdeveniment es processi de forma fiable i segura.
La clau està en no subestimar el detall de la URL. Configurar-la com a constant, capturar el raw body abans de qualsevol parseu i utilitzar sempre comparació en temps constant són pràctiques que, encara que senzilles, marquen la diferència entre una integració robusta i una que falla en producció. Amb el suport d'un equip expert en programari a mida i serveis cloud, pots evitar els dolors de cap que generen aquests errors i centrar-te en l'important: el teu negoci.
