Un webhook rebut encara ha de demostrar d’on ve
Una aplicació rep un avís que sembla correcte: té un tipus d’esdeveniment, un identificador i les dades esperades. Això no demostra qui l’ha enviat. Si l’avís pot posar en marxa una acció, comprovar-ne l’origen forma part del procés.
Un exemple concret: la signatura de Stripe
La documentació de Stripe recomana verificar els esdeveniments rebuts al webhook. El seu exemple utilitza el cos de la petició, la capçalera Stripe-Signature i el secret de l’endpoint amb la funció constructEvent(). No n’hi ha prou amb veure una capçalera amb aquest nom: cal validar-la segons el mecanisme del proveïdor.
Cada servei té el seu propi contracte. No copiïs el nom d’una capçalera o una regla de Stripe a una altra integració assumint que funcionarà igual. Revisa la documentació del servei i la biblioteca que utilitza l’aplicació abans d’acceptar l’esdeveniment com a verificat.
El cos original importa
Stripe explica que la verificació necessita el cos original de la petició, sense canvis. Afegir espais, reordenar propietats o transformar el contingut abans de comprovar la signatura pot fer que la validació falli.
Aquest detall afecta la configuració del servidor: alguns frameworks processen el JSON automàticament abans que el codi del webhook el rebi. Comprova l’ordre dels components i conserva el cos necessari per verificar-lo. No desactivis la comprovació per fer desaparèixer l’error; separa el problema de configuració de l’acceptació de dades no verificades.
Entorns diferents, secrets diferents
Un altre error habitual que descriu Stripe és utilitzar el secret d’un endpoint diferent. Els esdeveniments reenviats amb la seva eina de desenvolupament i un endpoint configurat al panell no comparteixen necessàriament el mateix secret. Identifica l’entorn i la destinació abans de configurar la verificació.
Per provar el circuit, utilitza les eines de prova oficials i comprova que un missatge alterat no desencadena l’acció. Evita exposar secrets o dades de clients als registres compartits. Una signatura vàlida tampoc decideix quina acció correspon: després cal validar el tipus d’esdeveniment i aplicar les regles de negoci. Rebre, verificar i actuar són passos diferents.