Test Slack Webhooks Locally

From a stuck handler to a live Slack delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL — something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3In api.slack.com/apps → your app → Event Subscriptions, paste your LocalCan URL with your path into Request URL, e.g. https://your-app-12.localcan.dev/slack/events. Slack immediately POSTs a type:"url_verification" payload; echo its challenge back with HTTP 200 to verify. The same URL also goes in Interactivity & Shortcuts and Slash Commands. The Signing Secret used to verify all of them is under Basic Information → App Credentials.
4. 4Slack has no “resend last delivery” button. Re-save the Request URL to fire a fresh url_verification, or trigger a real event in a workspace where the app is installed: @-mention the bot (app_mention), add a reaction (reaction_added), run the slash command, or click a Block Kit button (block_actions). Return a non-2xx or stall past 3s and Slack retries on its own, carrying x-slack-retry-num.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body — expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Header

X-Slack-Signature

Algorithm

HMAC-SHA256, lowercase hex, prefixed v0=

What's signed

Slack signs the basestring v0:{X-Slack-Request-Timestamp}:{raw body} — the literal v0, a colon, the timestamp value from the X-Slack-Request-Timestamp header, another colon, then the exact bytes of the request body. HMAC-SHA256 with your Signing Secret, hex-encoded, gives the v0= value in X-Slack-Signature. Sign your own clock instead of the header’s timestamp, or parse the body first, and the digest can never match.

Secret

The Signing Secret from api.slack.com/apps → your app → Basic Information → App Credentials. It is a plain UTF-8 string used as the HMAC key (in practice a lowercase hex string, no prefix). One secret covers Events API, slash commands, and interactivity — they are all signed identically. It is not the deprecated Verification Token and not an xoxb- / xapp- token.

import express from 'express'
import crypto from 'crypto'

const signingSecret = process.env.SLACK_SIGNING_SECRET // from Basic Information

const app = express()

// Slack signs the RAW body — capture the exact bytes BEFORE any JSON/urlencoded parser.
app.post(
  '/slack/events',
  express.raw({ type: () => true }),
  (req, res) => {
    const sig = req.headers['x-slack-signature'] // v0=...
    const ts = req.headers['x-slack-request-timestamp']
    const body = req.body // a Buffer of the raw bytes

    // Reject requests older than 5 minutes (replay protection).
    if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 60 * 5) {
      return res.status(400).send('stale timestamp')
    }

    // basestring = "v0:" + timestamp + ":" + rawBody
    const basestring = 'v0:' + ts + ':' + body.toString('utf8')
    const expected =
      'v0=' +
      crypto.createHmac('sha256', signingSecret).update(basestring).digest('hex')

    // Constant-time compare; bail if lengths differ so timingSafeEqual won't throw.
    const a = Buffer.from(expected)
    const b = Buffer.from(String(sig))
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send('bad signature')
    }

    const payload = JSON.parse(body.toString('utf8'))

    // First save of the Request URL: echo the challenge back.
    if (payload.type === 'url_verification') {
      return res.status(200).send(payload.challenge)
    }

    // Ack within 3 seconds, then process async.
    res.status(200).end()
    // handle payload.event ...
  },
)