Què és un webhook? Com les apps s'avisen entre elles

Un webhook és un missatge automàtic que un servei envia a la teva app en el moment exacte en què passa alguna cosa. Quan el pagament d'un client és correcte, Stripe envia un webhook a una adreça de la teva app dient «pagament correcte, aquí tens els detalls», i la teva app reacciona: marca la comanda com a pagada, envia el rebut, desbloqueja el compte. En resum: una API és la teva app fent una pregunta a un altre servei; un webhook és l'altre servei que crida la teva app per explicar-li alguna cosa.

Per què importa quan construeixes amb IA

Tan bon punt la teva app accepta pagaments, rep formularis d'una altra eina o es connecta a serveis com GitHub, Shopify o un calendari, et trobaràs amb webhooks. Normalment són la manera correcta de saber que alguna cosa ha passat, però també són on les apps construïdes amb IA sovint fallen de manera subtil:

• L'endpoint accepta qualsevol sol·licitud, de manera que qualsevol pot falsificar un esdeveniment de «pagament correcte».
• La app concedeix accés a la pàgina de retorn del pagament en lloc del webhook, de manera que la gent que tanca la pestanya aviat no obté el que ha pagat, i la gent que troba la URL d'èxit ho obté gratis.
• El mateix esdeveniment arriba dues vegades i el client rep dues comandes o dos correus.

Saber com funcionen els webhooks et permet demanar les proteccions des del principi.

Una analogia de la vida quotidiana: un SMS de lliurament

Pots saber si el teu paquet ha arribat de dues maneres. Pots anar a la porta cada deu minuts a comprovar-ho (això és sondeig —la teva app crida una API repetidament per preguntar «hi ha alguna novetat?»). O el transportista et pot enviar un SMS quan l'hagi lliurat (això és un webhook).

El SMS és clarament millor —sempre que te'n puguis fiar. Si qualsevol pogués enviar-te un missatge de «paquet lliurat», voldries alguna manera de saber que realment ve del transportista. I si tenies el telèfon apagat quan va arribar el SMS, voldries que el transportista ho tornés a intentar més tard. Aquestes dues preocupacions —verificació i reintents— són gairebé tot el que fa els webhooks complicats.

Com funciona un webhook, pas a pas

1. Crees un endpoint al backend de la teva app: una URL com https://lamevaapp.com/webhooks/stripe que accepti sol·licituds POST.
2. Registres aquesta URL amb el proveïdor i tries quins esdeveniments vols (per exemple, «pagament completat» i «subscripció cancel·lada»).
3. El proveïdor et dona un secret de signatura. El guardes com a secret al teu servidor —consulta variables d'entorn i secrets.
4. Passa un esdeveniment. El proveïdor envia una sol·licitud HTTP a la teva URL amb un cos JSON que la descriu, més una capçalera de signatura.
5. La teva app verifica la signatura, registra l'ID de l'esdeveniment, respon ràpidament amb un codi d'èxit (200) i després fa la feina.
6. Si la teva app no respon amb èxit, molts proveïdors ho tornen a intentar més tard.

Signatures

Una signatura demostra que la sol·licitud va venir del proveïdor i que no s'ha alterat. Stripe, per exemple, calcula un HMAC (una mena d'empremta amb clau) amb SHA-256 sobre el cos de la sol·licitud i un timestamp, utilitzant el secret de signatura, i l'envia en una capçalera Stripe-Signature. La teva app fa el mateix càlcul amb la seva còpia del secret; si els resultats coincideixen, la sol·licitud és genuïna. Com que el timestamp també està signat, pots rebutjar sol·licituds antigues que algú hagi gravat i reproduït més tard —les biblioteques de Stripe tenen una tolerància per defecte de cinc minuts, segons la seva documentació a setembre de 2026.

Un detall pràctic: la signatura es calcula sobre el cos en brut de la sol·licitud. Si el teu framework analitza i reformata el JSON abans de verificar-lo, la comprovació falla. És un error molt habitual.

Reintents, duplicats i ordre

Els proveïdors són diferents, així que consulta la documentació de cadascun. A setembre de 2026:

La documentació de Stripe també diu que no es garanteix que els esdeveniments arribin en l'ordre en què van passar, i que el mateix esdeveniment pot arribar més d'una vegada en alguna ocasió, per la qual cosa recomana fer seguiment dels IDs d'esdeveniment.

La lliçó general es manté per a qualsevol proveïdor: els esdeveniments poden arribar tard, més d'una vegada i desordenats. El teu gestor ha de ser idempotent —processar el mateix esdeveniment dues vegades té el mateix efecte que processar-lo una vegada.

Un exemple pràctic: desbloquejar un curs de pagament

Vens un curs en línia. Un estudiant fa clic a Comprar, paga a la pàgina de pagament allotjada de Stripe i és retornat al teu lloc.

La manera fràgil: la pàgina «gràcies» desbloqueja el curs. Si l'estudiant tanca el navegador durant la redirecció, ha pagat però no té accés. Si algú endevina la URL de la pàgina de gràcies, obté accés sense pagar.

La manera amb webhook:

1. Quan Stripe confirma el pagament, envia un esdeveniment checkout.session.completed a /webhooks/stripe.
2. El teu backend verifica la signatura amb el secret de signatura. Si falla, respon 400 i no fa res.
3. Comprova si aquest ID d'esdeveniment ja s'ha processat. Si és així, respon 200 i s'atura.
4. Desa l'ID de l'esdeveniment, respon 200 i després concedeix accés a l'estudiant i envia un correu de benvinguda.
5. La pàgina de gràcies només diu «Pagament rebut —el teu curs apareixerà en un moment» i comprova l'estat d'accés de l'estudiant.

Després, si es cancel·la una subscripció o falla una targeta, altres esdeveniments de webhook indiquen a la teva app que retiri o pausi l'accés. Així és com els productes de subscripció es mantenen sincronitzats amb la facturació —consulta què és el SaaS i com afegir pagaments a la teva app.

Termes clau

• Endpoint: la URL de la teva app que rep els webhooks.
• Esdeveniment / payload: què ha passat, i les dades que ho descriuen (normalment JSON).
• Secret de signatura: el secret compartit que serveix per verificar les signatures.
• Idempotent: segur d'executar més d'una vegada amb el mateix resultat.
• Sondeig (polling): preguntar repetidament a una API si hi ha canvis en lloc d'esperar un webhook.
• Túnel: una eina que dona a un ordinador portàtil una URL pública temporal perquè els webhooks hi arribin durant el desenvolupament.

Errors habituals i idees equivocades

• No verificar les signatures. La URL de l'endpoint no és un secret. La verificació és el que fa que la sol·licitud sigui de confiança.
• Fer tasques lentes abans de respondre. Enviar correus o generar PDF abans de respondre pot provocar timeouts, que disparen reintents, que causen duplicats.
• Suposar que arriba exactament una vegada i en ordre. Registra els IDs d'esdeveniment i no confiïs en l'ordre d'arribada.
• Fer servir una URL de previsualització. Els webhooks necessiten una adreça pública i estable. Les previsualitzacions privades i localhost no són accessibles des d'internet; fes servir la teva URL publicada (o un túnel mentre proves).
• Barrejar secrets de prova i en viu. Els proveïdors sovint emeten secrets de signatura diferents per als modes de prova i en viu. Desa'ls tots dos i utilitza el correcte.
• Confiar cegament en el payload per a decisions importants. Per a accions d'alt risc, és raonable obtenir l'estat més recent de l'API del proveïdor després de rebre l'esdeveniment.

Què demanar a la teva eina de construcció IA

Afegeix un endpoint POST /webhooks/stripe al servidor. Verifica la signatura de Stripe fent servir el cos de la sol·licitud en brut i el secret STRIPE_WEBHOOK_SECRET. Rebutja les signatures no vàlides amb 400. Desa cada ID d'esdeveniment i salta els esdeveniments ja processats. Respon 200 ràpidament i després gestiona checkout.session.completed marcant la comanda com a pagada i enviant el rebut. Registra el tipus d'esdeveniment. No concedeixis accés des de la pàgina d'èxit del pagament.

Després, prova-ho: envia un esdeveniment de prova des del panell del proveïdor, envia'l una segona vegada i envia una sol·licitud amb una signatura incorrecta. Només el primer hauria de canviar alguna cosa.

Webhooks a Mythex

Mythex no executa un servei de webhooks separat; demanes a l'agent que afegeixi un endpoint de webhook al backend de la teva pròpia app, i apuntes el proveïdor a la teva URL publicada, ja que els webhooks necessiten una adreça pública. El secret de signatura va als secrets del projecte, i si el canvies en una app en viu, has de tornar a publicar. La recepta de la documentació sobre gestió de webhooks té un prompt inicial, i les plantilles de botiga són un bon punt de partida per a apps que accepten pagaments.

Preguntes