La verificació de signatures de webhook a Shopify sovint falla per dues raons principals: l'HMAC està codificat en Base64 (no en hexadecimal), i cal utilitzar el cos cru (raw body) abans de qualsevol anàlisi JSON. Aquest article ofereix una guia completa sobre com implementar una verificació correcta, quin secret utilitzar i com evitar els paranys més comuns. A més, veurem com les solucions de Q2BSTUDIO us poden ajudar a construir integracions robustes i segures.
Quan Shopify envia un webhook, inclou una capçalera X-Shopify-Hmac-Sha256 que conté un HMAC-SHA256 calculat sobre el cos de la sol·licitud original (bytes sense processar). La clau per generar aquest HMAC és el client secret de la vostra aplicació, que trobareu al Tauler de Socis (Partner Dashboard). El resultat es codifica en Base64, a diferència de Stripe o GitHub que utilitzen hexadecimal. Si copieu codi de verificació d'un altre servei, probablement fallarà perquè la codificació és diferent.
El primer error comú és intentar verificar l'HMAC després que Express (o qualsevol altre framework) hagi analitzat el cos amb express.json(). L'anàlisi modifica els bytes originals: elimina espais en blanc, canvia l'ordre de les propietats, normalitza caràcters. L'HMAC que calculeu sobre un objecte re-serialitzat mai coincidirà amb el de Shopify. La solució és capturar el cos cru abans de qualsevol anàlisi. A Express, utilitzeu express.raw({ type: '*/*' }) a la ruta del webhook. Verifiqueu l'HMAC amb aquest buffer i, només si és vàlid, analitzeu el JSON manualment.
El segon error és utilitzar .digest('hex') en lloc de .digest('base64'). La majoria d'exemples de verificació de webhooks (per exemple, per a Stripe o GitHub) fan servir hexadecimal perquè així es lliura la signatura en aquests serveis. Shopify, en canvi, utilitza Base64. Si només canvieu el nom de la capçalera però manteniu la codificació hexadecimal, la comparació sempre fallarà. Assegureu-vos que el vostre codi generi l'HMAC en Base64 i el compareu amb el valor de la capçalera.
Un altre punt crític és la comparació en si mateixa. Utilitzar una igualtat normal (===) pot ser vulnerable a atacs de temporització. Sempre heu d'emprar una funció de comparació de temps constant, com crypto.timingSafeEqual de Node.js. Abans de cridar-la, verifiqueu que tots dos buffers tinguin la mateixa longitud, perquè en cas contrari llançarà una excepció. A més, recordeu respondre amb un codi 401 si la signatura no coincideix; Shopify espera un 200 ràpid per considerar que l'esdeveniment s'ha lliurat correctament.
El secret utilitzat també és font freqüent d'errors. Shopify signa amb el client secret de la vostra aplicació, no amb la clau API ni amb el token d'accés. Si teniu diverses aplicacions (per exemple, una de desenvolupament i una de producció), cadascuna té el seu propi client secret. Verificar un webhook d'una aplicació amb el secret d'una altra donarà un error constant. Comproveu sempre que feu servir el secret correcte.
Més enllà dels detalls tècnics, la fiabilitat dels webhooks és un desafiament de negoci. Si el vostre servidor cau, està en mig d'un desplegament o simplement triga massa a processar un esdeveniment, Shopify reintentarà fins a 8 vegades en unes 4 hores. Si tots els reintents fallen, la subscripció al webhook es desactiva automàticament. Això significa que podeu perdre esdeveniments crítics com comandes, reemborsaments o compliments. Aquí és on una arquitectura robusta marca la diferència.
A Q2BSTUDIO, entenem que la infraestructura tècnica ha de ser resilient. Per això oferim serveis de desenvolupament d'aplicacions a mida que integren mecanismes de cua de missatges, reintents amb backoff exponencial i dead-letter queues. També implementem solucions al núvol amb AWS o Azure per garantir alta disponibilitat. Els nostres equips apliquen pràctiques de ciberseguretat avançada per assegurar que cada webhook sigui verificat correctament, evitant suplantacions i atacs de replay.
A més, la intel·ligència artificial té un paper cada cop més important en l'automatització de processos. Per exemple, podem entrenar agents d'IA per analitzar patrons en els esdeveniments de Shopify i activar accions personalitzades al vostre backend. Això, combinat amb dashboards de Business Intelligence (Power BI), us permet visualitzar en temps real el flux de comandes, devolucions i mètriques de negoci. Tot sobre una base de ciberseguretat sòlida que protegeix les vostres dades i les dels vostres clients.
Si voleu evitar els maldecaps que comporta la gestió manual de webhooks, considereu externalitzar aquesta capa de fiabilitat. Plataformes com EventDock ofereixen un punt d'entrada únic que verifica, emmagatzema i reenvia esdeveniments amb garanties de lliurament. Però fins i tot si decidiu implementar el vostre propi sistema, els consells d'aquest article us ajudaran a evitar els paranys més comuns. Recordeu: el cos cru, la codificació Base64 i el secret correcte són els vostres millors aliats.
En resum, verificar un webhook de Shopify no és complex, però requereix atenció a tres detalls clau: capturar el raw body abans de qualsevol anàlisi, utilitzar digest('base64') i comparar amb timingSafeEqual. Si afegiu una capa de resiliència amb cues i reintents, la vostra integració serà molt més robusta. A Q2BSTUDIO estem llestos per ajudar-vos a dissenyar aquesta arquitectura, ja sigui des de zero o millorant-ne una d'existent. Contacteu-nos per a una consultoria sense compromís.
