Docs / Integration API contract

Verifying requests from this server

Every request this server makes to an app — slash commands, button presses, form submissions, event deliveries and URL checks — is signed as Slack signs:

basestring = "v0:" + <X-Slack-Request-Timestamp> + ":" + <raw request body>
signature  = "v0=" + hex(HMAC-SHA256(signing secret, basestring))

The signature is sent as X-Slack-Signature with its timestamp in X-Slack-Request-Timestamp, and repeated as X-OwnBase-Signature and X-OwnBase-Request-Timestamp. A verifier written for Slack, including Bolt's, works unchanged. Verify against the raw body, compare in constant time, and reject a timestamp more than five minutes from your clock so a captured request cannot be replayed:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySlackRequest(signingSecret, headers, rawBody, now = Date.now()) {
  const timestamp = Number(headers["x-slack-request-timestamp"]);
  const signature = String(headers["x-slack-signature"] ?? "");
  if (!Number.isInteger(timestamp) || Math.abs(now / 1000 - timestamp) > 300) return false;
  const expected =
    "v0=" + createHmac("sha256", signingSecret).update(`v0:${timestamp}:${rawBody}`).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Every outbound call has four seconds to answer (Slack allows three) and a reply of at most 64 KB. Redirects are not followed. By default the server will not call a private or loopback address; start it with --allow-private-hooks for an app running on the same network.

This page is made from docs/INTEGRATIONS.md.