Connecting your app
Send real Slack interaction payloads from the browser to an existing Bolt app, signed the way Slack signs them.
Everything so far handles interactions locally with onAction/onSubmit/onOptions. To instead
drive a real Slack app (the same Bolt or raw HTTP app you’d deploy), point the provider at your
app’s request URL. Two pieces keep the signing secret off the page: httpTransport on the client,
and a relay on your server that signs the request the way Slack does.
The signing secret never reaches the browser: only your server has it. The browser only ever talks to its own origin.
Client: httpTransport
@nkootstra/block-kit/transport is browser-safe (no Node built-ins), so it can ship in your page
bundle. httpTransport returns onPayload/onSubmit/onClose/onOptions ready to spread onto the
provider:
import { BlockKitProvider, Message } from "@nkootstra/block-kit";
import { httpTransport } from "@nkootstra/block-kit/transport";
export function App() {
return (
<BlockKitProvider
{...httpTransport({
url: "/api/slack/relay",
onResponse: (payload, result) => console.log("delivered", result.status),
onError: (payload, error) => console.error("failed to deliver", error),
})}
>
<Message
blocks={[
{
type: "actions",
block_id: "actions",
elements: [
{
type: "button",
action_id: "approve",
text: { type: "plain_text", text: "Approve" },
},
],
},
]}
/>
</BlockKitProvider>
);
}
urlstring
Where payloads are POSTed: your relay route, or an app with signature verification disabled (only ever one running on your own machine).
stringtoken?string
The relay's token, sent as Authorization: Bearer <token>. A development secret, not a Slack credential.
stringheaders?HeadersInit
Extra headers sent with every payload.
HeadersInitfetch?typeof fetch
Injectable for tests; defaults to the global fetch.
typeof fetchonResponse?(payload, result) => void
Called with every payload sent and the app's reply.
(payload, result) => voidonError?(payload, error) => void
Called when delivery fails or the app answers with a non-2xx status.
(payload, error) => voidblock_actions and view_closed are sent fire-and-forget. A view_submission’s response_action
reply is parsed and applied to the modal automatically, and a block_suggestion’s reply fills the
external select, the same as if you’d wired up onSubmit/onOptions by hand.
Server: createInteractionRelay
@nkootstra/block-kit/server runs on your server (it imports node:crypto) and exports a plain
(Request) => Response handler that signs the payload httpTransport sent and forwards it to your
app’s real request URL, then relays the app’s reply back:
import { createInteractionRelay } from "@nkootstra/block-kit/server";
export const relay = createInteractionRelay({
requestUrl: "https://internal.example.com/slack/events",
signingSecret: process.env.SLACK_SIGNING_SECRET!,
});
requestUrlstring
Your app's Slack request URL (an Events API / interactivity endpoint).
stringsigningSecretstring
The same signing secret your app is configured with.
stringtoken?string
When set, a request without Authorization: Bearer <token> gets a 401 before it's read. See Protecting the relay.
stringonError?(error: unknown) => void
Called when the app couldn't be reached. The browser only gets a 502, without the URL or the reason.
(error: unknown) => voidfetch?typeof fetch
Injectable for tests; defaults to the global fetch.
typeof fetchNext.js route handler
import { createInteractionRelay } from "@nkootstra/block-kit/server";
export const POST = createInteractionRelay({
requestUrl: process.env.SLACK_REQUEST_URL!,
signingSecret: process.env.SLACK_SIGNING_SECRET!,
});
Point httpTransport({ url: "/api/slack/relay" }) at that route and you’re done.
Bun.serve
import { createInteractionRelay } from "@nkootstra/block-kit/server";
const relay = createInteractionRelay({
requestUrl: process.env.SLACK_REQUEST_URL!,
signingSecret: process.env.SLACK_SIGNING_SECRET!,
});
Bun.serve({
port: 3000,
fetch(request) {
const url = new URL(request.url);
if (url.pathname === "/api/slack/relay") return relay(request);
return new Response("Not found", { status: 404 });
},
});
The relay works with any framework that speaks the Fetch API Request/Response pair: Hono, Vite
middleware, Cloudflare Workers, and so on.
Protecting the relay
Out of the box the relay refuses two things: a body over 1 MB, and a request a browser sends from
another site’s page. httpTransport marks every request with a header a cross-site HTML form can’t
set, so a page you happen to visit while your dev server runs can’t post a payload to
localhost and have the relay sign it. Calls from your own server, which send no Origin, pass.
That doesn’t stop someone who can reach the route directly. When it’s reachable beyond your
machine, give the relay a token and pass the same value to httpTransport:
import { createInteractionRelay } from "@nkootstra/block-kit/server";
export const POST = createInteractionRelay({
requestUrl: process.env.SLACK_REQUEST_URL!,
signingSecret: process.env.SLACK_SIGNING_SECRET!,
token: process.env.NEXT_PUBLIC_RELAY_TOKEN,
});
const transport = httpTransport({
url: "/api/slack/relay",
token: process.env.NEXT_PUBLIC_RELAY_TOKEN,
});
A request without Authorization: Bearer <token>, or with a different one, gets a 401 before the
relay reads it. The token is compared in constant time.
The token ships in your page, so anyone who can open the page can read it. That’s fine because it’s a development secret shared between the page and its own relay, not a Slack credential: it can’t reach Slack, and you can change it whenever you like. Never reuse the signing secret or a bot token as the relay’s token.
Why the signing secret must stay server-side
Slack’s apps verify every incoming request with an HMAC computed from the signing secret, the request
timestamp and the raw body (X-Slack-Signature / X-Slack-Request-Timestamp); an unsigned request is
rejected. If the secret shipped in your page’s JavaScript, anyone could read it out of the bundle and
forge requests to your app as if they came from Slack. Keeping signingSecret only on the server, and
having the browser talk only to your own relay route, is the same trust boundary a real Slack app
relies on.
The relay signs each request with a fresh timestamp, so your app’s replay protection (Bolt rejects
a request more than five minutes old) doesn’t limit what reaches it through the relay: every request
it forwards is new. That’s another reason the relay belongs on your machine or behind a token, not
in front of an app that holds real data.
Signing without the relay
If you want to send one interaction yourself rather than wiring up the full transport/relay pair
(a background job, a test, a CLI), use the lower-level signing helpers directly, also from
@nkootstra/block-kit/server:
import { sendInteraction, signSlackRequest, postSigned } from "@nkootstra/block-kit/server";
import { buildBlockActionsPayload } from "@nkootstra/block-kit";
const result = await sendInteraction({
requestUrl: process.env.SLACK_REQUEST_URL!,
signingSecret: process.env.SLACK_SIGNING_SECRET!,
payload: buildBlockActionsPayload({
action: {
type: "button",
action_id: "approve",
block_id: "actions",
action_ts: "1719000000.000100",
},
state: {},
container: { type: "message", messageTs: "1719000000.000100" },
}),
});
console.log(result.status, result.responseAction);
signSlackRequest?(signingSecret, timestamp, body) => string
Slack's v0 signing scheme: "v0=" + HMAC-SHA256(secret, v0:{ts}:{body}), hex-encoded.
(signingSecret, timestamp, body) => stringpostSigned?(opts) => Promise<Response>
POSTs an already form-encoded body with the signature headers set, unparsed.
(opts) => Promise<Response>sendInteraction?(opts) => Promise<SendInteractionResult>
postSigned, plus JSON-encoding the payload and parsing the app's response_action reply.
(opts) => Promise<SendInteractionResult>