Slack Bolt with Express: ExpressReceiver and customRoutes, Tested
Two ways to serve your own HTTP routes next to a Bolt JS app: ExpressReceiver with receiver.router, or customRoutes on the built-in receiver. We ran both with Bolt 5.1.0 and Express 5.3.0 on 17 November 2026, plus the body-parser mistake that makes every slash command fail.
On this page
To run Slack Bolt for JavaScript on Express, create an ExpressReceiver with your signing secret, pass it to new App({ receiver }), and add your own routes on receiver.router. If you only need a few extra routes such as /health, skip Express and use the customRoutes option on the default receiver. We ran both in a test workspace on 17 November 2026 with @slack/bolt 5.1.0, Express 5.3.0 (the version Bolt installs) and Node 22.23.5, behind a Cloudflare quick tunnel, and sent real slash commands to each. One mistake broke everything: a global express.json() placed before Bolt.
ExpressReceiver with your own routes
const { App, ExpressReceiver } = require("@slack/bolt");
const receiver = new ExpressReceiver({
signingSecret: process.env.SLACK_SIGNING_SECRET,
});
// Your own routes live on the same Express app as /slack/events
receiver.router.get("/health", (req, res) => res.send("ok"));
receiver.router.post("/webhooks/github", (req, res) => res.status(202).send("queued"));
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
receiver,
logLevel: process.env.LOG_LEVEL || "info",
});
app.command("/sg1117", async ({ command, ack }) => {
await ack("Express receiver got: " + command.text);
});
app.event("app_mention", async ({ event, say }) => {
await say({ text: "Hi from ExpressReceiver", thread_ts: event.ts });
});
(async () => {
await app.start(3000);
console.log("ExpressReceiver app on :3000");
})();
receiver.router is an Express router mounted on the same app that serves /slack/events. What each route answered through the tunnel:
| Request | Answer |
|---|---|
GET /health | 200 ok |
POST /webhooks/github | 202 queued |
POST /slack/events with no Slack headers | 401, and Bolt logged Request verification failed (code: slack_bolt_receiver_authenticity_error, message: Slack request signing verification failed. Some headers are missing.) |
Signed url_verification body | 200, {"challenge":"..."} as application/json |
GET /nope | Express's own 404 HTML page |
/sg1117 hello from express in Slack | Ephemeral reply "Express receiver got: hello from express" |
The Events API page accepted the URL after one Retry, since Bolt answers the challenge for you:
customRoutes without Express
Bolt's default HTTPReceiver takes a customRoutes array. Handlers get Node's plain req and res, not Express objects, and path parameters land in req.params:
const { App } = require("@slack/bolt");
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
signingSecret: process.env.SLACK_SIGNING_SECRET,
customRoutes: [
{
path: "/health",
method: ["GET"],
handler: (req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("ok");
},
},
{
path: "/orders/:id",
method: ["GET"],
handler: (req, res) => {
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ id: req.params.id }));
},
},
],
});
app.command("/sg1117", async ({ command, ack }) => {
await ack("customRoutes app got: " + command.text);
});
(async () => {
await app.start(3000);
console.log("customRoutes app on :3000");
})();
| Request | Answer |
|---|---|
GET /health | 200 ok |
GET /orders/42 | 200 {"id":"42"} |
POST /slack/events unsigned | 401, log Failed to verify authenticity: header x-slack-signature did not have the expected type (received undefined, expected string) |
GET /nope | 404 with an empty body, log Unhandled HTTP request (GET) made to /nope |
| Slash command | Ephemeral reply, as with Express |
Choose customRoutes when you need a health check or one callback URL. Choose ExpressReceiver when you already have Express middleware such as auth, sessions or a static site to share the port with.
Never appear "away" on Slack again
Cloud-based. No downloads. Works 24/7 even when your laptop is off.
The mistake: a body parser before Bolt
Many Express apps start with app.use(express.json()). If you hand such an app to ExpressReceiver, Bolt never sees the request body:
const express = require("express");
const { App, ExpressReceiver } = require("@slack/bolt");
const server = express();
// The mistake: a global body parser before Bolt sees the request
server.use(express.urlencoded({ extended: true }));
server.use(express.json());
server.get("/health", (req, res) => res.send("ok"));
const receiver = new ExpressReceiver({
signingSecret: process.env.SLACK_SIGNING_SECRET,
app: server,
});
const app = new App({ token: process.env.SLACK_BOT_TOKEN, receiver });
app.command("/sg1117", async ({ command, ack }) => {
await ack("own Express app got: " + command.text);
});
(async () => {
await app.start(3000);
console.log("own express app on :3000");
})();
Every request to /slack/events failed. Bolt logged Failed to read request body (error: InternalServerError: stream is not readable), a signed url_verification got 400, and in Slack the command failed with "the app did not respond":
The parser read the stream first, and Bolt needs the raw bytes to check the signature. The fix is to keep body parsers off the Slack path and put them only on your own routes:
const express = require("express");
const { App, ExpressReceiver } = require("@slack/bolt");
const server = express();
server.get("/health", (req, res) => res.send("ok"));
const receiver = new ExpressReceiver({
signingSecret: process.env.SLACK_SIGNING_SECRET,
app: server,
});
// Body parsers only on your own routes, after Bolt is mounted
server.post("/api/orders", express.json(), (req, res) => res.json({ got: req.body }));
const app = new App({ token: process.env.SLACK_BOT_TOKEN, receiver });
app.command("/sg1117", async ({ command, ack }) => {
await ack("own Express app (fixed) got: " + command.text);
});
(async () => {
await app.start(3000);
console.log("own express app (fixed) on :3000");
})();
With this version the slash command answered normally, the signed challenge returned 200, and POST /api/orders with {"sku":"A-1"} returned {"got":{"sku":"A-1"}}. The log does not mention the signature at all. With Bolt 5.1.0 the message is about the unreadable stream, so search your logs for "stream is not readable".
Which receiver to pick
| You need | Use |
|---|---|
| A health check or one webhook next to Slack | customRoutes |
| Existing Express middleware, sessions or a web UI on the same port | ExpressReceiver with receiver.router or your own app |
| No public URL at all | Socket Mode (socketMode: true and an xapp- token) |
| A serverless platform | Your platform's adapter, or a Cloudflare Worker |
Whichever you choose, the app's bot token goes in token, and the signing secret goes in signingSecret (default receiver) or in the receiver's own options (ExpressReceiver). If you upgrade from Bolt 4 to 5, read our Bolt JS v5 notes first.
FAQ
Can I use Express 4 with Bolt 5? Bolt 5.1.0 depends on Express 5.3.0 and installed it next to our app. We did not test Express 4.
Where is the Slack endpoint path set?
Both receivers listen on /slack/events by default. Pass endpoints: "/your/path" to change it, and use the same path for the request URL in your app settings.
Why does my slash command say the app did not respond?
Slack waits about 3 seconds for the ack(). A body parser in front of Bolt, a crash before ack() or slow work before ack() all end the same way. Our Bolt error handling tests show each case.
Stop Jiggling Your Mouse.
Join hundreds of remote workers who never worry about their Slack status. Set it up once, stay green forever.
Related Articles
Slack Bolt Middleware: Global and Listener, Tested
Global middleware runs for every request and listener middleware for one listener. We ran both in Bolt for Python and Bolt for JavaScript on 20 November 2026 and logged what Slack did when next() was skipped: Python answered 404 and Slack sent the event again.
Testing a Slack Bolt App with pytest: What Worked, What Did Not
Three layers that tested a Bolt for Python app on 17 November 2026: pure functions, listeners called with fakes, and signed requests through app.dispatch against a local mock Web API, plus one live check. A subclassed WebClient and the default threading both made tests fail; here is why.
Chat SDK for Slack: A Streaming Thread Bot, Tested
Vercel's Chat SDK (chat 4.45.0 with @chat-adapter/slack) ran a Slack thread bot for us on 17 November 2026 with no Vercel deploy: a plain Node server, a quick tunnel, streamed replies, thread subscriptions and markdown conversion. Here is the code, what Slack showed and what it does that raw Bolt does not.