feat(HTTPReceiver): add invalidRequestSignatureHandler callback by mvanhorn · Pull Request #2827 · slackapi/bolt-js

mvanhorn · 2026-03-24T08:24:30Z

Adds invalidRequestSignatureHandler to HTTPReceiver.

Why this matters

PR #2154 added this callback to AwsLambdaReceiver. HTTPReceiver was missing it. Now HTTP apps can hook into signature verification failures too.

Changes

HTTPReceiver.ts: New HTTPReceiverInvalidRequestSignatureHandlerArgs interface. New option in HTTPReceiverOptions. Constructor wiring with noop default. Fires in the signature-verification catch block with rawBody, signature header, and timestamp.

ExpressReceiver support can follow in a separate PR.

Testing

Codex ran npm test against the change. All existing tests pass.

Refs #2156

This contribution was developed with AI assistance (Claude Code).

mwbrooks · 2026-03-30T03:47:39Z

Hey @mvanhorn 👋🏻 This sounds like a reasonable enhancement and thank you the explaining the motivation related to the AwsLambdaReceiver.

I'll add a few maintainers to review this PR 👏🏻

In the meantime, can you please add tests for the new changes? I imagine that'll be one of the first requests from the reviewers as well. 🙇🏻

salesforce-cla · 2026-03-30T16:00:01Z

Thanks for the contribution! Unfortunately we can't verify the commit author(s): Matt Van Horn <m***@m***.local>. One possible solution is to add that email to your GitHub account. Alternatively you can change your commits to another email and force push the change. After getting your commits associated with your GitHub account, sign the Salesforce Inc. Contributor License Agreement and this Pull Request will be revalidated.

mvanhorn · 2026-03-30T16:00:49Z

Added tests in b8d77a0 - three cases covering: custom handler receives correct args on signature failure, default noop handler doesn't throw, and missing headers pass undefined for signature/ts. Full suite passes (407 tests).

zimeg · 2026-03-30T16:55:18Z

@mvanhorn Super amazing changes more 🧪 ✨

The most recent commit author might've been configured strange - would it be possible to force push changes with an author that can sign the CLA? 🏛️

Rambles now but slackapi/node-slack-sdk#1135 becomes most curious 👾

Adds an optional invalidRequestSignatureHandler to HTTPReceiver, matching the callback added to AwsLambdaReceiver in PR slackapi#2154. When signature verification fails, the handler fires with the raw body, signature header, and timestamp. Defaults to a noop. Refs slackapi#2156

Cover three scenarios: custom handler called with correct args on signature failure, default noop handler doesn't throw, and missing headers pass undefined for signature/ts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

mvanhorn · 2026-03-30T18:22:06Z

Fixed the commit author in 4aa2f01 — both commits now use my GitHub-linked noreply address. CLA should pass on recheck. All 407 tests still passing.

Re: node-slack-sdk#1135 — interesting, hadn't seen that. The invalidRequestSignatureHandler pattern here could serve as a stepping stone toward that kind of unified request validation.

codecov · 2026-04-08T17:04:25Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.00%. Comparing base (29167c5) to head (436ae8d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2827      +/-   ##
==========================================
+ Coverage   93.59%   94.00%   +0.41%     
==========================================
  Files          44       44              
  Lines        7855     7892      +37     
  Branches      687      698      +11     
==========================================
+ Hits         7352     7419      +67     
+ Misses        498      468      -30     
  Partials        5        5

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

changeset-bot · 2026-04-08T17:35:28Z

🦋 Changeset detected

Latest commit: 468f0bd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@slack/bolt	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

zimeg

@mvanhorn Thanks for the updates to authorship and quick responses! 🎆

I think this approach moves things in a solid direction and want to leave a few comments that might be useful toward slackapi/node-slack-sdk#1135 in immediate improvement 👾

In quick reference:

Required ts and signature values might be easier to reference in application code but I understand values from unexpected requests might be missing
The HTTP interface name might or might not match the AWS interface? I'm curious toward an eventual shared interface 👻
The placeholder logs might be nice to move into the default implementation so overriding handlers have control of this output?

A note for documentation might also be nice to include, and brings up a callout that we could surface this as a top-level App option as well:

HTTPReceiver options can be passed into the App constructor, just like the Bolt app options.

I'm curious to your thoughts for all of these behaviors! Thanks for bringing this feature so far already too.

zimeg · 2026-04-12T21:43:18Z

+export interface HTTPReceiverInvalidRequestSignatureHandlerArgs {
+  rawBody: string;
+  signature: string | undefined;
+  ts: number | undefined;
+}


🐣 note: Here are findings of the adjacent implementation:

bolt-js/src/receivers/AwsLambdaReceiver.ts

Lines 51 to 57 in a8b7880

export interface ReceiverInvalidRequestSignatureHandlerArgs {

rawBody: string;

signature: string;

ts: number;

awsEvent: AwsEvent;

awsResponse: Promise<AwsResponse>;

}

Suggested change

export interface HTTPReceiverInvalidRequestSignatureHandlerArgs {

rawBody: string;

signature: string | undefined;

ts: number | undefined;

}

export interface HTTPReceiverInvalidRequestSignatureHandlerArgs {

rawBody: string;

signature: string;

ts: number;

}

👁️‍🗨️ thought: I'd be curious to use default values here and perhaps matching the adjacent interface name, but I'm less confident about the second point...

zimeg · 2026-04-12T22:10:13Z

+            signature: req.headers['x-slack-signature'] as string | undefined,
+            ts: req.headers['x-slack-request-timestamp'] ? Number(req.headers['x-slack-request-timestamp']) : undefined,


Suggested change

signature: req.headers['x-slack-signature'] as string | undefined,

ts: req.headers['x-slack-request-timestamp'] ? Number(req.headers['x-slack-request-timestamp']) : undefined,

signature: req.headers['x-slack-signature'] as string,

ts: Number(req.headers['x-slack-request-timestamp']),

👾 suggestion: This might bring more strict typing?

zimeg · 2026-04-12T22:51:58Z

  logLevel?: LogLevel;
  processBeforeResponse?: boolean;
  signatureVerification?: boolean;
+  invalidRequestSignatureHandler?: (args: HTTPReceiverInvalidRequestSignatureHandlerArgs) => void;


📚 suggestion: While it's not shared in other options right now we might add @jsdoc to this?

Let's also surface this in documentation here:

🔗 https://docs.slack.dev/tools/bolt-js/reference#receiver-options

@zimeg

…handler Per @zimeg: - Tighten HTTPReceiverInvalidRequestSignatureHandlerArgs: signature is now string (default '') and ts is number (default 0) when headers are missing, matching AwsLambdaReceiver's ReceiverInvalidRequestSignatureHandlerArgs shape and removing the 'string | undefined' / 'number | undefined' awkwardness in override handlers. - Add logger to the args so override handlers can emit their own structured output using the receiver's configured logger. - Move the default warn log into defaultInvalidRequestSignatureHandler so overrides can fully suppress or replace the warning instead of having it always emitted before the handler runs. Format mirrors AwsLambdaReceiver's default: 'Invalid request signature detected (X-Slack-Signature: ..., X-Slack-Request-Timestamp: ...)'. - Add jsdoc on the invalidRequestSignatureHandler option describing the default behavior, the 401 response, and the override contract. - Update the two HTTPReceiver.spec.ts test cases that previously asserted 'undefined' signature/ts to check the new defaults ('', 0) and to verify a logger is passed to the handler.

mvanhorn · 2026-04-15T02:04:56Z

Thanks for the careful review @zimeg. Pushed 3c1f24c addressing most of the feedback:

Interface shape (HTTPReceiverInvalidRequestSignatureHandlerArgs):

signature: string (default '' when the header is missing) and ts: number (default 0), matching the ReceiverInvalidRequestSignatureHandlerArgs shape on the AWS receiver so override handlers don't have to keep narrowing string | undefined.
Added logger: Logger to the args so overrides can emit their own output using the receiver's configured logger.

Default handler behavior:

Moved the default warn log into defaultInvalidRequestSignatureHandler so overriding handlers can fully suppress/replace it. Format mirrors the AWS receiver's default: Invalid request signature detected (X-Slack-Signature: ..., X-Slack-Request-Timestamp: ...).
Stricter header extraction at the call site ((req.headers['x-slack-signature'] as string) ?? '', Number(req.headers['x-slack-request-timestamp']) || 0).

Docs:

Added jsdoc on the invalidRequestSignatureHandler option describing the 401 contract and the override behavior. Happy to also PR the reference doc update at https://docs.slack.dev/tools/bolt-js/reference#receiver-options - let me know if you'd like that here or as a follow-up.

Held off on:

Renaming HTTPReceiverInvalidRequestSignatureHandlerArgs to match the AWS ReceiverInvalidRequestSignatureHandlerArgs or unifying them. Unifying makes sense but would touch the AWS awsEvent / awsResponse fields, which feels like scope creep on this PR. Happy to do it as a follow-up if you'd prefer.
Surfacing as a top-level App option. Also a follow-up candidate - the App constructor currently lets HTTPReceiver options pass through via receiverOptions, so users can opt in today.

Updated the two existing tests that asserted undefined signature/ts to check the new defaults and the logger. npm test green (467 passing), biome clean, typecheck clean.

zimeg

@mvanhorn Thank you for bringing this to a great place! I'm requesting another change for a scoped PR but am hoping we can extend this more in follow ups as needed after landing this 🎁

zimeg · 2026-04-22T05:47:01Z

+  rawBody: string;
+  signature: string;
+  ts: number;
+  logger: Logger;


Suggested change

logger: Logger;

🪓 quibble: I'm curious for adding this too but perhaps it's better to revisit in a follow up PR to match for AwsLambdaReceiver as well? This motivates slackapi/node-slack-sdk#1135 more for me!

🔬 note: Please do let me know if implementations without it find error or strange patterns, either in calling code or this package! I'm curious for examples that we can support as well.

@zimeg

…er args Mirror the AwsLambdaReceiver pattern: the default handler reaches for `this.logger` directly instead of plumbing a `logger` argument through the interface. Removes `logger: Logger` from `HTTPReceiverInvalidRequestSignatureHandlerArgs`, the call site in `requestListener`, and the destructure in `defaultInvalidRequestSignatureHandler`. Per @zimeg on PR slackapi#2827, keeping the interface symmetrical with `ReceiverInvalidRequestSignatureHandlerArgs` on `AwsLambdaReceiver` leaves room for a shared interface in a follow-up PR. Tests updated to assert `logger` is no longer present on args; full HTTPReceiver suite (20 tests) passes with build, lint, and type tests green.

mvanhorn · 2026-04-22T23:23:20Z

@zimeg done in 468f0bd. Dropped logger: Logger from HTTPReceiverInvalidRequestSignatureHandlerArgs so the interface matches ReceiverInvalidRequestSignatureHandlerArgs on AwsLambdaReceiver. The default handler now reaches for this.logger.warn directly (same pattern AwsLambdaReceiver uses in its defaultInvalidRequestSignatureHandler).

Leaves the eventual shared-interface refactor to the follow-up PR you mentioned in #1135.

Verified: npm test passes (build + biome + tsd + 20 HTTPReceiver unit tests including the 3 invalidRequestSignatureHandler cases, updated to assert logger is no longer present on args).

mvanhorn requested a review from a team as a code owner March 24, 2026 08:24

salesforce-cla Bot added the cla:signed label Mar 24, 2026

mwbrooks added enhancement M-T: A feature request for new functionality semver:minor labels Mar 30, 2026

mwbrooks requested review from WilliamBergamin and zimeg March 30, 2026 03:47

salesforce-cla Bot added cla:missing and removed cla:signed labels Mar 30, 2026

mvanhorn and others added 2 commits March 30, 2026 11:18

mvanhorn force-pushed the osc/2156-invalid-sig-handler branch from b8d77a0 to 4aa2f01 Compare March 30, 2026 18:18

salesforce-cla Bot added cla:signed and removed cla:missing labels Mar 30, 2026

Merge branch 'main' into osc/2156-invalid-sig-handler

c2bdaf9

zimeg mentioned this pull request Apr 8, 2026

build: automate release packaging and version bumps with changesets #2851

Merged

2 tasks

Merge branch 'main' into osc/2156-invalid-sig-handler

5c78be9

zimeg added 2 commits April 12, 2026 14:01

Merge branch 'main' into osc/2156-invalid-sig-handler

137fe26

chore: changeset

6ceb696

zimeg reviewed Apr 12, 2026

View reviewed changes

Merge branch 'main' into osc/2156-invalid-sig-handler

436ae8d

zimeg requested changes Apr 22, 2026

View reviewed changes

	export interface ReceiverInvalidRequestSignatureHandlerArgs {
	rawBody: string;
	signature: string;
	ts: number;
	awsEvent: AwsEvent;
	awsResponse: Promise<AwsResponse>;
	}

		signature: req.headers['x-slack-signature'] as string \| undefined,
		ts: req.headers['x-slack-request-timestamp'] ? Number(req.headers['x-slack-request-timestamp']) : undefined,

Conversation

mvanhorn commented Mar 24, 2026

Why this matters

Changes

Testing

Uh oh!

mwbrooks commented Mar 30, 2026

Uh oh!

salesforce-cla Bot commented Mar 30, 2026

Uh oh!

mvanhorn commented Mar 30, 2026

Uh oh!

zimeg commented Mar 30, 2026

Uh oh!

mvanhorn commented Mar 30, 2026

Uh oh!

codecov Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

changeset-bot Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

zimeg Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

zimeg Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

zimeg Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

zimeg Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

mvanhorn commented Apr 15, 2026

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

zimeg Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

mvanhorn commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Apr 8, 2026 •

edited

Loading

changeset-bot Bot commented Apr 8, 2026 •

edited

Loading