El secret de signatura d'un webhook és una credencial, no un detall de configuració. Envieu-lo com enviaríeu una contrasenya: confirmeu qui el rep, lliureu-lo per un canal que no en desi còpies i assegureu-vos que acaba en un magatzem de secrets i no en un tiquet. Dit breument: un enllaç secret d'un sol ús enviat a un contacte verificat, amb les instruccions de configuració a part.
La resta d'aquesta guia tracta l'elecció del canal, les comprovacions abans d'enviar-lo, què n'ha de fer el client i com gestionar la rotació i els problemes sense tornar a enganxar mai el secret.
Quin canal ha de portar el secret?
Trieu el canal amb dues preguntes: podeu confirmar qui el pot obrir, i quantes còpies deixa enrere? El correu i el xat fallen en la segona, perquè cada missatge es conserva, se sincronitza i s'exporta molt després que el lliurament hagi acabat.
| Mètode | Què us ofereix | Què cal comprovar abans d'enviar |
|---|---|---|
| Portal de clients amb autenticació | Accés nominal que podeu revocar | Que el compte és del contacte correcte |
| Enllaç secret d'un sol ús | Es destrueix després d'una obertura i no deixa res al missatge | L'adreça a què l'envieu, comprovada per separat |
| Missatgeria xifrada | Protecció en trànsit | Qui més pot obrir aquella conversa |
Un portal de clients amb inici de sessió individual és una bona primera opció quan n'hi ha un. Doneu accés a una persona concreta, no a un fil compartit del projecte, i traieu-l'hi quan el lliurament hagi acabat.
Un enllaç d'un sol ús manté la credencial fora del correu o del missatge de xat que feu servir per coordinar-vos. Amb LinkPilot, el secret es xifra al vostre navegador abans de desar-se, la còpia desada es destrueix després d'una obertura i podeu fer que l'enllaç caduqui al cap d'una hora, un dia o una setmana. Els plans Pro hi afegeixen una frase de contrasenya que comuniqueu per un canal separat. Aquests controls limiten el lliurament. No substitueixen la comprovació que a l'altra banda hi ha la persona correcta.
La missatgeria xifrada és l'alternativa quan cap de les dues opcions anteriors és pràctica. El xifratge en trànsit no arregla un missatge enviat a l'adreça equivocada ni un grup amb més membres dels que cal, de manera que la comprovació del destinatari pesa encara més.
Trieu el que trieu, reserveu el correu i el xat sense xifrar per a la coordinació. Fins i tot els serveis que xifren en trànsit deixen fora del vostre control la retenció, les còpies de seguretat i l'accés als comptes.
Verifiqueu el client i el destinatari
Un canal segur no serveix de res si el secret va a la safata d'entrada equivocada. Abans d'enviar-lo, confirmeu que la persona que el demana és la responsable de la integració i que la via que penseu fer servir és realment seva.
- Confirmeu la identitat amb un registre conegut. Feu servir una fitxa de contacte de confiança, una relació comercial existent o el procediment habitual del client. Un sol·licitant nou, un canvi sobtat de contacte o una urgència poc habitual mereixen una comprovació independent.
- Llegiu l'adreça caràcter per caràcter, sobretot quan la copieu d'un tiquet o d'un missatge recent. Els noms semblants i les safates compartides són on es produeixen els errors.
- Reviseu qui més hi té accés. Abans de compartir-lo per un portal o un espai de treball, mireu-ne la llista de membres i traieu-ne qui no necessiti la credencial.
- Confirmeu el lliurament per un segon canal. Si l'enllaç ha anat per correu, pregunteu per un número de telèfon conegut o pel canal habitual del projecte si l'accés ha funcionat. No hi inclogueu el secret.
Compartiu el secret amb l'única persona que configurarà l'endpoint i deixeu que el desi al magatzem de secrets del client. Si el necessiten diversos enginyers, qui el veu s'ha de decidir amb els controls d'accés d'aquell magatzem, no amb una còpia per a cadascun.
Prepareu el secret abans del lliurament
Decidiu a què pertany la credencial, on l'ha de conservar el client i quant de temps ha d'estar obert el lliurament. Amb aquesta preparació, la rotació i la resolució de problemes posteriors són molt menys confuses.
- Un secret per client o per endpoint. Si el reutilitzeu, una sola exposició arriba a totes les integracions que comparteixen el valor, i rotar-lo per a un client les interromp totes. Porteu un registre intern de l'endpoint a què pertany cada secret, sense duplicar el valor a les notes del projecte.
- Deseu la vostra còpia en un gestor de secrets. No en un fitxer de text local, un tiquet o un document compartit. La mateixa disciplina val per a compartir claus d'API: limiteu qui pot arribar a la credencial i feu que el lliurament duri poc.
- Fixeu un termini per recollir-lo. Doneu al client prou temps per obtenir el valor i acabar la configuració, i no més. Un enllaç que es destrueix després d'una obertura i caduca al cap d'un dia cobreix la majoria de lliuraments; si el termini passa, creeu-ne un de nou en lloc de reobrir l'antic.
- Envieu les instruccions de configuració per separat. L'URL de l'endpoint, la capçalera de la signatura i els passos de verificació van a la documentació del client o al canal del projecte. Si els manteniu separats del secret, una pàgina d'instruccions copiada no és alhora una credencial copiada.
Ajudeu el client a desar-lo i fer-lo servir de manera segura
El lliurament no s'acaba quan el client pot llegir el valor. S'acaba quan el servidor el pot llegir de manera segura i el fa servir per verificar les signatures entrants.
- Deseu-lo en un gestor de secrets o en una variable d'entorn protegida que el procés del servidor pugui llegir, amb l'accés limitat a l'aplicació i a les persones que la gestionen.
- Mantingueu-lo fora del codi font, dels registres i del contingut dels webhooks. El secret serveix per calcular o verificar una signatura. No viatja mai al cos de la petició, i no ha d'aparèixer a la sortida de depuració, als repositoris ni als tiquets de suport. Comproveu què captura l'eina de desplegament abans d'activar els diagnòstics detallats.
- Verifiqueu les signatures al servidor. El receptor torna a calcular la signatura sobre el cos en brut de la petició amb el secret compartit i la compara amb la capçalera que ha posat l'emissor. La signatura demostra que la petició és autèntica i no s'ha alterat; no xifra el contingut. La guia de HackerOne sobre com signar webhooks explica per què importen tant el cos en brut com el secret correcte.
- Feu una prova amb un esdeveniment. Demaneu al client que confirmi que s'accepta una signatura vàlida i es rebutja una que s'ha espatllat expressament. Així es detecten els errors habituals: el secret d'un altre endpoint o un cos analitzat abans de la verificació. Mantingueu separades les credencials de prova i les de producció quan la integració ho permeti.
Reduïu el risc després del lliurament
El lliurament ha de deixar un registre útil, no un rastre de còpies de més.
- Anoteu qui estava autoritzat i quan. Registreu el destinatari, l'endpoint o el client i l'hora del lliurament. Mai el valor. Si no podeu saber si un enllaç s'ha obert o qui tenia accés a una carpeta compartida, preneu-ho com un motiu per ajustar el procés la vegada següent.
- Roteu-lo davant de qualsevol sospita d'exposició. Un secret enganxat en un tiquet, enviat a l'adreça equivocada o trobat en un registre ja no és privat. Genereu-ne un de nou, actualitzeu l'endpoint i invalideu el valor antic. Suprimir un enllaç compartit no desfà una exposició; només la rotació ho fa.
- Acordeu ara el procés de rotació. Decidiu qui demana, crea i instal·la el substitut, si la implementació admet un breu solapament i com provareu el valor nou abans de retirar l'antic. Un procediment conegut és millor que un intercanvi urgent enmig d'una caiguda del servei.
- Feu neteja. Quan el client confirmi que l'ha recollit, revoqueu l'accés temporal i suprimiu les còpies que hagin quedat en esborranys, tiquets i notes. Comproveu les regles de retenció de cada sistema implicat; suprimir un missatge d'una vista rarament l'elimina de les còpies de seguretat.
Resoleu problemes sense exposar el secret
Un problema de lliurament no és motiu per tornar a enviar la credencial per un canal més feble. Primer esbrineu quina de tres coses falla: el client no pot recuperar el secret, no pot configurar l'endpoint, o rep peticions però no en pot validar les signatures.
- La recuperació ha fallat o el termini ha vençut. Torneu a confirmar el destinatari i feu un nou lliurament controlat. No enganxeu el valor en un tiquet i no demaneu al client que us torni el seu per comparar-los.
- Les signatures no coincideixen. Gairebé sempre és un problema de les dades d'entrada de la verificació: el secret d'un altre endpoint, un cos que s'ha reformatat abans de calcular el hash o una capçalera mal llegida. Demaneu al client que faci la prova amb un esdeveniment conegut des de les eines de prova de l'emissor.
- Les peticions no arriben mai. És un problema de lliurament o d'encaminament, no de credencials. Comproveu les marques de temps, els codis de resposta i la selecció de l'endpoint abans que ningú pensi a rotar el secret. La documentació sobre webhooks de Stripe és un bon model per separar el registre d'endpoints i el lliurament d'esdeveniments de la verificació de signatures.
- Compartiu diagnòstics sense dades sensibles. N'hi ha prou amb l'identificador de l'esdeveniment, la marca de temps, l'endpoint i la categoria de l'error. Traieu-ne el secret, la signatura completa quan sigui sensible i els camps privats del contingut, i comproveu que no en quedi res abans d'enviar una petició d'exemple.
Verifiqueu el destinatari, lliureu el secret una sola vegada per un canal que no el conservi, assegureu-vos que acaba en un magatzem de secrets i roteu-lo sense dubtar si s'ha pogut filtrar. Per al patró general dels enllaços d'un sol ús en els fluxos de treball d'enginyeria, vegeu compartir enllaços de manera segura per a desenvolupadors.