Skip to content
Block Kit for React
Esc
↑↓navigate↵open⌘Jpreview
On this page

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>
  );
}
PropType
urlstring

Where payloads are POSTed: your relay route, or an app with signature verification disabled (only ever one running on your own machine).

Typestring
token?string

The relay's token, sent as Authorization: Bearer <token>. A development secret, not a Slack credential.

Typestring
headers?HeadersInit

Extra headers sent with every payload.

TypeHeadersInit
fetch?typeof fetch

Injectable for tests; defaults to the global fetch.

Typetypeof fetch
onResponse?(payload, result) => void

Called with every payload sent and the app's reply.

Type(payload, result) => void
onError?(payload, error) => void

Called when delivery fails or the app answers with a non-2xx status.

Type(payload, error) => void

block_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!,
});
PropType
requestUrlstring

Your app's Slack request URL (an Events API / interactivity endpoint).

Typestring
signingSecretstring

The same signing secret your app is configured with.

Typestring
token?string

When set, a request without Authorization: Bearer <token> gets a 401 before it's read. See Protecting the relay.

Typestring
onError?(error: unknown) => void

Called when the app couldn't be reached. The browser only gets a 502, without the URL or the reason.

Type(error: unknown) => void
fetch?typeof fetch

Injectable for tests; defaults to the global fetch.

Typetypeof fetch

Next.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);
PropType
signSlackRequest?(signingSecret, timestamp, body) => string

Slack's v0 signing scheme: "v0=" + HMAC-SHA256(secret, v0:{ts}:{body}), hex-encoded.

Type(signingSecret, timestamp, body) => string
postSigned?(opts) => Promise<Response>

POSTs an already form-encoded body with the signature headers set, unparsed.

Type(opts) => Promise<Response>
sendInteraction?(opts) => Promise<SendInteractionResult>

postSigned, plus JSON-encoding the payload and parsing the app's response_action reply.

Type(opts) => Promise<SendInteractionResult>

Last updated on