{"id":17644,"library":"express-x-hub","title":"Express X-Hub Signature Middleware","description":"The `express-x-hub` package provides an Express.js middleware for validating X-Hub-Signature requests. It was designed to ensure the integrity of incoming webhooks, particularly useful for platforms like Facebook real-time updates and GitHub webhooks, by verifying the request body against a secret using the `X-Hub-Signature` header. The current and only stable version is 1.0.4, last published in October 2015. This package is no longer actively maintained or updated, making it effectively abandoned. Its primary differentiation was its specific focus on adding validation methods directly to the `req` object (`req.isXHub`, `req.isXHubValid()`) within the Express middleware flow, requiring placement *before* any body parsing middleware. It does not provide official TypeScript types.","status":"abandoned","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/alexcurtis/express-x-hub","tags":["javascript","express","x-hub","xhub","signature","middleware","facebook","realtime","updates"],"install":[{"cmd":"npm install express-x-hub","lang":"bash","label":"npm"},{"cmd":"yarn add express-x-hub","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-x-hub","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only (published October 2015). Direct ESM `import` statements will fail without Node.js CJS interop or transpilation. Use `require` for compatibility.","wrong":"import xhub from 'express-x-hub';","symbol":"xhub","correct":"const xhub = require('express-x-hub');"},{"note":"A boolean property added to the Express `req` object, indicating if the request includes an X-Hub signature.","symbol":"req.isXHub","correct":"if (!req.isXHub) { /* handle non-xhub request */ }"},{"note":"A method added to the Express `req` object that returns a boolean, verifying the request body against the X-Hub signature using the configured secret.","symbol":"req.isXHubValid","correct":"if (!req.isXHubValid()) { /* handle invalid signature */ }"}],"quickstart":{"code":"import express from 'express';\nimport bodyParser from 'body-parser';\nconst xhub = require('express-x-hub');\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\nconst XHUB_SECRET = process.env.XHUB_SECRET || 'your-super-secret-key';\n\nif (!XHUB_SECRET || XHUB_SECRET === 'your-super-secret-key') {\n  console.warn('WARNING: XHUB_SECRET is not set or using default. Please set `process.env.XHUB_SECRET` for production.');\n}\n\n// IMPORTANT: express-x-hub middleware MUST be placed before body-parser\napp.use(xhub({ algorithm: 'sha1', secret: XHUB_SECRET }));\napp.use(bodyParser.json());\napp.use(bodyParser.urlencoded({ extended: true }));\n\napp.post('/webhook', (req, res) => {\n  console.log('Received webhook request.');\n\n  // Check if it's an X-Hub request at all\n  if (!req.isXHub) {\n    console.log('Request is not X-Hub.');\n    return res.status(400).send('No X-Hub Signature Found');\n  }\n\n  // Validate the X-Hub signature\n  if (!req.isXHubValid()) {\n    console.warn('Invalid X-Hub Signature!');\n    return res.status(401).send('Invalid X-Hub Signature');\n  }\n\n  // If valid, process the request\n  console.log('X-Hub Signature is valid. Processing request body:', req.body);\n  res.status(200).json({ status: 'X-Hub Is Valid', data: req.body });\n});\n\napp.get('/', (req, res) => {\n  res.send('X-Hub test server running. Send POST requests to /webhook');\n});\n\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n  console.log(`Test with: curl -X POST -H \"X-Hub-Signature: sha1=your_test_signature\" -H \"Content-Type: application/json\" -d '{\"key\":\"value\"}' http://localhost:${PORT}/webhook`);\n});\n","lang":"javascript","description":"This quickstart sets up a basic Express server with the `express-x-hub` middleware to validate incoming webhooks. It demonstrates the critical middleware order (before `body-parser`) and how to use `req.isXHub` and `req.isXHubValid()` to handle and verify signed requests."},"warnings":[{"fix":"Ensure `app.use(xhub(...))` is called *before* `app.use(bodyParser.json())` or `app.use(bodyParser.urlencoded())`.","message":"The `express-x-hub` middleware *must* be mounted before any `body-parser` middleware. X-Hub signatures are calculated over the raw request body. If `body-parser` processes the request first, the raw body will be consumed and unavailable for `express-x-hub`, leading to validation failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate newer, actively maintained alternatives like `x-hub-signature` and its dedicated Express middleware. Be aware of potential API differences when migrating.","message":"The `express-x-hub` package (v1.0.4) was last published in October 2015 and appears to be unmaintained and effectively abandoned. While it still functions, consider migrating to a more actively maintained X-Hub-Signature validation library, such as `x-hub-signature` (which offers a separate middleware package `x-hub-signature-middleware` for Express) for better security and ongoing support.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Manually extend the `express.Request` interface in your project to include `isXHub: boolean` and `isXHubValid: () => boolean`. Create a declaration file (e.g., `src/types/express-x-hub.d.ts`) with content like: `declare namespace Express { interface Request { isXHub?: boolean; isXHubValid(): boolean; } }`.","message":"This package does not ship with official TypeScript declaration files. When used in a TypeScript project, the `req.isXHub` and `req.isXHubValid()` properties will not be recognized by the compiler, leading to type errors unless custom declaration merging is used.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Add a TypeScript declaration file (e.g., `src/types/express-x-hub.d.ts`) to your project to augment the `express.Request` interface. Example content: `declare namespace Express { interface Request { isXHub?: boolean; isXHubValid(): boolean; } }`. Ensure this file is included in your `tsconfig.json`.","cause":"Missing TypeScript type declarations for the custom properties `express-x-hub` adds to the Express `Request` object.","error":"Property 'isXHubValid' does not exist on type 'Request<{}, any, any, ParsedQs, Record<string, any>>'."},{"fix":"1. Verify the `secret` configured in the middleware matches the secret used by the webhook sender. 2. Ensure the `X-Hub-Signature` header is present and correctly formatted in the incoming request. 3. Crucially, confirm that `express-x-hub` is mounted *before* any `body-parser` or other middleware that consumes the raw request body.","cause":"The X-Hub signature in the request header does not match the signature calculated from the request body using the provided secret, or the X-Hub-Signature header is entirely missing (if `strict` option is `true`). This can also happen if the `express-x-hub` middleware is placed *after* a `body-parser` middleware, corrupting the raw body.","error":"Error: Invalid X-Hub Signature"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}