Una ruta que lee X-Shopify-Topic y envía el pedido, pero nunca comprueba X-Shopify-Hmac-Sha256, envía pedidos a cualquiera que encuentre la URL. Lo mismo ocurre con un HMAC calculado sobre JSON.stringify(req.body), con un twilio.webhook({ validate: false }) olvidado tras las pruebas o con una comprobación que devuelve true cuando falta el encabezado de la firma. Esta skill encuentra esos errores y otros siete errores de webhooks antes de que el endpoint salga a producción, y te explica cómo corregir cada uno.

Tu agente ejecuta un escáner sobre tu código de webhooks en JavaScript y TypeScript (Express, Next.js, NestJS, Hono, Koa, Fastify), Python (Flask, FastAPI, Django, AWS Lambda), PHP (Laravel), Ruby (Rails, Sinatra) y Go. Encuentra cada ruta y trata una ruta POST como receptor de GitHub, GitLab, Shopify, Twilio, Paddle, Lemon Squeezy, Polar, Svix, Clerk, Resend, SendGrid, Mailgun, Square, Razorpay o Coinbase cuando lee los encabezados o el payload de eventos de ese proveedor. Revisa cada ruta por separado y conoce las llamadas de verificación de cada proveedor (octokit verify, authenticate.webhook, twilio.webhook(), paddle.webhooks.unmarshal, validateEvent, verifyWebhook, Svix Webhook.verify y más), así que las rutas verificadas, y las cubiertas por un middleware, decorador o helper de verificación en otro archivo escaneado (Express app.use, wrappers de handlers en Go, middleware de Next.js, Rails before_action y Rack::TwilioWebhookAuthentication), no se reportan. Omite comentarios y archivos de prueba y nunca ejecuta tu código. Devuelve BLOCK, REVIEW o NOT FLAGGED, con el archivo, la línea, el motivo y una alternativa más segura. Los secretos nunca se muestran.

Qué revisa

BLOCK (corregir antes de publicar)

• W01: rutas POST que leen los encabezados o el payload de webhooks de un proveedor sin verificar la firma
• W02: secretos de firma de webhooks, claves de proveedores y tokens de GitLab escritos en el código
• W03: verificación desactivada o que deja pasar al fallar (validate: false, octokit receive(), dejar pasar la petición cuando falta la firma o el secreto, rechazar solo cuando hay firma o continuar tras una verificación fallida)

REVIEW (revisar antes del lanzamiento)

• W11: firmas comparadas con ==, ===, strcmp o bytes.Equal en lugar de una comparación de tiempo constante
• W12: HMAC calculados sobre JSON reserializado en lugar del cuerpo original de la petición
• W13: comprobaciones escritas a mano de firmas con marca de tiempo sin ventana temporal (repetición)
• W14: eventos de pedidos y pagos procesados sin comprobar el id del evento ni los duplicados
• W15: el encabezado heredado X-Hub-Signature con SHA-1 de GitHub o el encabezado de firma heredado de Square
• W16: secretos de webhooks leídos del entorno con un valor por defecto fijado en el código
• W17: verificación que una opción del entorno o un flag SKIP_ o DISABLE_ puede desactivar

Qué incluye

• El escáner (Python 3.9+, solo biblioteca estándar)
• Una guía de reglas con el motivo, una alternativa más segura y un enlace a la documentación del proveedor para cada regla
• Un proyecto de ejemplo arriesgado y otro seguro, y el informe real que genera el escáner sobre el arriesgado

Limitaciones

Lee el código tal como está escrito: no ve la verificación hecha por un API gateway, un proxy o código fuera de la carpeta escaneada, y no sigue valores construidos a lo largo de varios archivos. Una ruta que solo menciona a un proveedor en su path no se trata como receptor de webhooks. Los webhooks de Stripe no están cubiertos. NOT FLAGGED no es una garantía.

Contenido

Un archivo ZIP con 19 archivos: SKILL.md, el escáner en scripts/ (6 archivos de Python), references/rules.md (cada regla con su motivo y una alternativa más segura) y examples/ (10 archivos de ejemplo más report.md, la salida real del escáner sobre el ejemplo arriesgado).

Cómo usarlo: Es una skill para agentes: una carpeta con un archivo SKILL.md y scripts de Python que puede ejecutar un agente de programación con IA como Claude Code, Cursor o Codex CLI. Descomprímela en la carpeta de skills de tu agente (para Claude Code: ~/.claude/skills/) y luego pide a tu agente que revise tu proyecto. Los scripts también funcionan por sí solos con Python 3.9 o posterior, sin nada que instalar. Solo leen tus archivos: sin acceso a la red y sin enviar nada a ningún sitio.