Com protegir els webhooks de CRM i e-commerce davant d’esdeveniments falsos o duplics

Un webhook no és només una URL que rep dades d’una plataforma externa. És una porta d’entrada que pot crear una comanda, actualitzar una fitxa de client, emetre un avís, modificar existències o iniciar una automatització. Si s’accepta un esdeveniment d’origen no verificat, repetit o amb dades inesperades, una integració útil pot provocar accions de negoci indegudes.

El problema requereix combinar controls tècnics i operatius: saber quin proveïdor pot cridar, quins esdeveniments estan permesos, quines dades són acceptables i quina conseqüència concreta pot tenir cada missatge. L’objectiu no és bloquejar les integracions, sinó dissenyar-les perquè una fallada, un reintent o una notificació anòmala no es converteixin automàticament en una comanda, un càrrec, un canvi d’estat o una alerta falsa.

El risc: una notificació pot convertir-se en una acció empresarial

En una integració habitual, una passarel·la de pagament, un e-commerce, un CRM o una eina de missatgeria envia una notificació de servidor a servidor a un endpoint propi. El receptor no hauria de tractar aquestes dades com a fiables pel simple fet d’arribar des d’una integració coneguda. OWASP identifica el consum insegur d’APIs com un risc quan una aplicació confia excessivament en serveis integrats i redueix els controls d’autenticació, xifratge o validació de les dades rebudes. [1]

Per exemple hipotètic, una botiga pot rebre l’esdeveniment «pagament confirmat» i alliberar una comanda sense comprovar-ne l’autenticitat, la referència interna o l’estat real. Un altre sistema podria rebre dues vegades una notificació d’alta de client i crear registres duplicats. L’impacte depèn de l’acció connectada al webhook, per la qual cosa convé avaluar cada endpoint com a part d’un procés de negoci i no com un detall menor de configuració.

Comenceu amb un inventari i un abast definit

Abans de canviar codi o regles d’automatització, elaboreu un inventari de webhooks. Per a cadascun, identifiqueu el proveïdor emissor, la URL receptora, els esdeveniments permesos, el sistema de destinació, la persona responsable, el mecanisme d’autenticació i la data de l’última revisió. Mantenir visibilitat sobre les APIs i les seves interfícies ajuda a reduir problemes derivats d’un inventari deficient o d’interfícies oblidades. [5]

També definiu què pot fer cada esdeveniment vàlid. Que una notificació estigui autenticada no significa que hagi de poder modificar qualsevol dada. Un esdeveniment de lliurament hauria d’actualitzar només l’estat d’enviament previst; no hauria de crear reemborsaments, canviar preus ni alterar permisos. Aquesta separació permet aplicar el principi de mínim efecte: cada missatge desencadena únicament l’acció que en justifiquen el tipus i el context.

• Documenteu el proveïdor, l’endpoint, la persona responsable, els esdeveniments acceptats i el sistema afectat.
• Indiqueu si l’esdeveniment conté dades personals, referències de comanda o informació sensible.
• Establiu una via de desactivació controlada per aturar temporalment una integració davant d’una incidència.

Verifiqueu l’origen abans d’executar l’acció

La ruta receptora ha d’utilitzar HTTPS i estar dedicada al webhook, sense convertir-la en un punt d’entrada genèric per a múltiples funcions. L’autenticació ha de seguir el mecanisme documentat per cada proveïdor: pot consistir en una signatura calculada sobre la sol·licitud, un secret associat a la subscripció o un token. NIST recomana incorporar l’autenticació de qui crida i la validació de sol·licituds i respostes com a controls de protecció d’APIs. [2]

La comprovació s’ha de fer abans d’iniciar efectes de negoci. Segons el model del proveïdor, pot implicar verificar una signatura, una marca temporal, un identificador de subscripció o els elements d’un JWT, com ara la caducitat, l’emissor, la signatura i l’audiència. Microsoft Graph descriu aquests patrons per a les seves notificacions i assenyala que la validació corresponent s’ha de completar abans de considerar una notificació com a autèntica. Els secrets s’han de mantenir fora del codi de l’aplicació i protegir-los adequadament. [3] [4]

• Rebutgeu les sol·licituds que no utilitzin el mètode HTTP previst.
• Compareu signatures o secrets mitjançant mecanismes segurs proporcionats pel llenguatge o la plataforma.
• Definiu límits de mida per a les sol·licituds i terminis raonables d’acceptació quan el proveïdor els admeti.

Valideu el contingut i feu que el processament sigui idempotent

Una signatura vàlida acredita el mecanisme d’enviament, però no substitueix la validació del contingut. Comproveu el tipus d’esdeveniment, l’estructura esperada, els camps obligatoris, els formats, els intervals, els valors permesos i les referències internes abans d’enviar dades a un ERP, CRM, WordPress o sistema de comandes. OWASP recomana validar i sanejar les dades que procedeixen d’APIs externes, ja que s’han de tractar com a informació no fiable. [1]

Per evitar duplicats, registreu un identificador únic de l’esdeveniment, el proveïdor i el resultat del seu processament. Abans de crear una comanda, emetre un tiquet o actualitzar l’estoc, consulteu si aquesta combinació ja ha estat acceptada. Si torna a arribar, registreu l’intent per investigar-lo, però no repetiu l’acció. La idempotència s’ha de dissenyar en el sistema receptor, perquè els emissors poden reenviar notificacions després d’errors o temps d’espera. [4]

• Conserveu una finestra de deduplicació adequada al cicle de cada procés.
• Relacioneu l’ID de l’esdeveniment amb la referència interna de comanda, client o transacció.
• Tracteu per separat els esdeveniments repetits, invàlids i pendents de revisió per facilitar-ne el seguiment.

Separeu la recepció de l’execució i deixeu evidència útil

Quan el proveïdor ho permeti, valideu ràpidament la notificació, deseu-la de manera controlada i envieu-la a una cua per processar-la posteriorment. Així es redueix el risc que una operació lenta provoqui un temps d’espera i un reintent de l’emissor. Microsoft Graph, per exemple, recomana confirmar o encuar aviat les notificacions i preveu reintents quan no rep una resposta satisfactòria. [4]

El processament diferit no elimina els controls: el treballador que consumeix la cua ha de tornar a aplicar regles d’idempotència, validar el context de negoci i registrar el resultat final. Deseu la data, el proveïdor, l’ID de l’esdeveniment, el resultat de l’autenticació, el resultat de la validació, l’acció sol·licitada i la referència interna. Eviteu conservar cossos complets si inclouen tokens, secrets o dades personals innecessàries. Proveu els fluxos només en entorns autoritzats, amb esdeveniments de prova documentats o de preproducció, incloent-hi signatures no vàlides, formats inesperats i reenviaments controlats.

• Definiu qui revisa els esdeveniments fallits o pendents.
• Alerteu sobre augments anòmals de rebutjos, duplicats o errors de processament.
• Reviseu l’inventari i les regles quan canviïn el proveïdor, l’endpoint o el procés de negoci.

Preguntes freqüents

N’hi ha prou amb ocultar la URL del webhook?

No. Una URL poc visible no substitueix l’autenticació ni la validació. L’endpoint ha de verificar el mecanisme admès pel proveïdor, acceptar únicament esdeveniments esperats i limitar les accions que pot iniciar.

Per què rebo el mateix webhook més d’una vegada?

Molts emissors reintenten una notificació si no reben una resposta adequada o si es produeix un temps d’espera. El receptor ho ha de preveure amb un identificador d’esdeveniment, un registre de processats i lògica idempotent per no repetir l’acció empresarial.

Què convé revisar després d’una incidència amb un webhook?

Reviseu l’evidència disponible: proveïdor, ID de l’esdeveniment, hora, resultat de l’autenticació, validació del contingut, acció sol·licitada i referència interna. Després, corregiu la regla concreta, proveu el canvi en un entorn autoritzat i actualitzeu l’inventari del webhook.