.jpg)
Quan s'integra un gestor de webhooks de GitHub amb la llibreria @octokit/webhooks, un dels errors més comuns en rebre les notificacions és que el servidor respon amb un codi 400 i un missatge que indica que falten les capçaleres x-hub-signature-256. Aquest problema sol aparèixer just després de configurar el webhook per primera vegada, però també pot manifestar-se en entorns de producció si no es revisen certs detalls de la infraestructura. La causa arrel gairebé sempre està relacionada amb l'absència d'un secret compartit entre GitHub i l'endpoint que processa els esdeveniments. Sense aquest secret, GitHub no signa els lliuraments i, per tant, omet les capçaleres de signatura que la llibreria espera. La solució immediata és definir un valor fort i aleatori a la configuració del webhook (dins del repositori o de l'organització) i passar exactament aquest mateix secret al constructor de Webhooks al codi. Un cop fet això, és recomanable reenviar un lliurament anterior des del panell de GitHub i verificar que la capçalera X-Hub-Signature-256 ja apareix a la petició.
No obstant, aquest error no sempre es deu a la manca de secret. De vegades, la petició que arriba al servidor no prové realment de GitHub, sinó d'eines de monitorització, tests locals amb curl o fins i tot d'escàners de seguretat que colpegen el mateix endpoint. Els lliuraments legítims de GitHub inclouen un User-Agent que comença amb GitHub-Hookshot/ i un identificador únic X-GitHub-Delivery. Si es necessita provar localment, el més fiable és copiar la càrrega útil i les capçaleres completes des de la secció Recent Deliveries del webhook, o simplement utilitzar l'opció de reenviar. Una altra font comuna del problema són els proxies, gateways o adaptadors serverless que filtren o reanomenen capçaleres no estàndard com les que comencen per X-. En aquests casos, un registre detallat de les capçaleres que arriben fins al controlador pot revelar si la capçalera es perd en algun punt intermedi. Per exemple, servidors nginx amb regles que ignoren guions baixos, o API Gateways amb llistes blanques de capçaleres, poden eliminar x-hub-signature-256 abans que arribi al codi de l'aplicació.
També és possible que el problema resideixi en una versió antiga de @octokit/webhooks que encara espera la capçalera antiga x-hub-signature (SHA-1). Les versions modernes requereixen la variant SHA-256, i GitHub envia ambdues quan el secret està configurat, per tant la solució pràctica segueix ser establir el secret i, a més, actualitzar la dependència a l'última versió compatible. Un altre aspecte a tenir en compte és la ruta on es munta el middleware: si s'utilitza un encaminador que també atén altres peticions, qualsevol sol·licitud no relacionada amb el webhook generarà aquest error 400. El més net és assignar una ruta exclusiva i dedicada a l'endpoint del webhook, evitant així falsos positius als logs.
Per a les empreses que desenvolupen aplicacions a mida i necessiten integrar notificacions en temps real des de plataformes com GitHub, resoldre aquest tipus d'errors de signatura és només un dels molts desafiaments tècnics que poden sorgir en la comunicació entre serveis. A Q2BSTUDIO, com a empresa de desenvolupament de programari a mida, abordem aquests problemes amb un enfocament integral que combina bones pràctiques de ciberseguretat —com la verificació de signatures i la gestió segura de secrets— amb una arquitectura robusta desplegada sobre serveis cloud AWS i Azure. La monitorització contínua dels webhooks i l'automatització de respostes davant fallades formen part de les solucions de intel·ligència artificial i serveis intel·ligència de negoci que oferim, permetent als nostres clients detectar incidències de forma proactiva i mantenir la integritat dels seus fluxos de dades. A més, quan es tracta d'analitzar el comportament dels esdeveniments, eines com Power BI ajuden a visualitzar mètriques de lliuraments, mentre que els agents IA i la ia per a empreses poden actuar sobre patrons repetitius per optimitzar processos. En definitiva, dominar la configuració dels webhooks de GitHub és un pas petit però essencial per garantir la fiabilitat de les integracions que sostenen les aplicacions a mida de qualsevol organització.
