feat(webhook): add opt-in retries to IncomingWebhook and WebhookTrigger by zimeg · Pull Request #2641 · slackapi/node-slack-sdk

zimeg · 2026-07-02T08:59:26Z

Summary

Adds opt-in retry support to @slack/webhook, mirroring the retryConfig convention already used by @slack/web-api's WebClient. Stacked on top of #2615 (the WebhookTrigger class), so this PR is scoped to just the retry change.

Both IncomingWebhook and WebhookTrigger accept a new retryConfig?: RetryOptions constructor option.
Adds retry-policies.ts with the same named policies exported by @slack/web-api — fiveRetriesInFiveMinutes, tenRetriesInAboutThirtyMinutes, rapidRetryPolicy — re-exported from the package entry point.
Each send() is wrapped in p-retry using the configured policy.

Default: no retries ({ retries: 0 }) when retryConfig is unset — preserves today's behavior; retries are opt-in.

Retry conditions (transient failures only):

Server errors (5xx) → retry
Network errors with no response → retry
All client errors (4xx), including rate limits (429) → abort immediately

Unlike @slack/web-api, 429 responses are not retried here. That client blocks its request queue to honor the Retry-After header; the webhook clients have no such queue, so a blind retry would ignore the server's backoff. Rate-limit handling is left to the caller, and all 4xx responses are treated the same.

retryConfig is a transport-only option and is stripped from the posted payload (like agent).

Consumed downstream by slackapi/slack-github-action#630, which passes its 0/5/10/RAPID input through to these policies.

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

🤖 Generated with Claude Code

changeset-bot · 2026-07-02T08:59:32Z

🦋 Changeset detected

Latest commit: 692179f

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

This PR includes changesets to release 1 package

Name	Type
@slack/webhook	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

codecov · 2026-07-02T09:01:14Z

Codecov Report

❌ Patch coverage is 90.81633% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.06%. Comparing base (e6604b6) to head (692179f).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@                   Coverage Diff                    @@
##           eden/webhook-trigger    #2641      +/-   ##
========================================================
+ Coverage                 88.97%   89.06%   +0.09%     
========================================================
  Files                        64       65       +1     
  Lines                     10363    10436      +73     
  Branches                    467      471       +4     
========================================================
+ Hits                       9220     9295      +75     
+ Misses                     1122     1120       -2     
  Partials                     21       21

Flag	Coverage Δ
cli-hooks	`89.06% <90.81%> (+0.09%)`	⬆️
cli-test	`89.06% <90.81%> (+0.09%)`	⬆️
logger	`89.06% <90.81%> (+0.09%)`	⬆️
oauth	`89.06% <90.81%> (+0.09%)`	⬆️
socket-mode	`89.06% <90.81%> (+0.09%)`	⬆️
web-api	`89.06% <90.81%> (+0.09%)`	⬆️
webhook	`89.06% <90.81%> (+0.09%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Default the payload to an empty object so send() can be called with no arguments, POSTing an empty body. send({}) continues to work unchanged. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

…webhook-retries # Conflicts: # packages/webhook/src/WebhookTrigger.ts

The `= {}` default now lives in the WebhookTrigger PR; keep the @param description unchanged here. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Use a falsy check so an empty-string URL is rejected up front rather than failing later at request time. Adds a guard test. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg

🔏 More words for the amazing reviewers.

zimeg · 2026-07-02T09:08:31Z

✂️ note: Matches the @slack/web-api implementation:

https://github.com/slackapi/node-slack-sdk/blob/f006ad409713741c5d398669c69ad98a7e090879/packages/web-api/src/retry-policies.ts

zimeg · 2026-07-03T16:44:27Z

+    "p-retry": "^4",
+    "retry": "^0.13.1"


🔍 note: These packages align with the @slack/web-api implementations:

node-slack-sdk/packages/web-api/package.json

Lines 61 to 62 in 12b94a2

"p-retry": "^4",

"retry": "^0.13.1"

zimeg · 2026-07-03T19:55:52Z

+    // Strip transport-only options so they do not leak into the posted payload.
    this.defaults.agent = undefined;
+    this.defaults.retryConfig = undefined;


📝 note: The default options passed to requests isn't ideal practice IMHO but we avoid regressions with this line.

WilliamBergamin

This looks great already 🚀

I think I might have mislead you around handling 429 responses, left a comment about this 😅

WilliamBergamin · 2026-07-06T15:53:41Z

+      it('does not retry a 4xx even when a retry policy is set', async () => {
+        const scope = nock('https://hooks.slack.com')
+          .post(/triggers/)
+          .reply(400);
+        const trigger = new WebhookTrigger(url, { retryConfig: rapidRetryPolicy });
+        try {
+          await trigger.send({ key: 'value' });
+          assert.fail('expected rejection');
+        } catch (error) {
+          assert.strictEqual((error as CodedError).code, ErrorCode.HTTPError);
+        }
+        // Only one interceptor is registered; a retry would leave it unmatched
+        // and scope.done() would throw.
+        scope.done();


Praise 💯

WilliamBergamin · 2026-07-06T16:08:37Z

+          const retryable = status === 429 || status >= 500;
+          const wrapped = httpErrorWithOriginal(error);
+          throw retryable ? wrapped : new AbortError(wrapped);


My mistake here, I may have mislead you on this 😅

429 status codes usually come with a retry header that informs the client on when it is appropriate to send requests. The web-api handles this by blocking the request queue of the client

The webhook package does not have the concept of request queues, and no one asked for it 🤔 Currently 429 responses are handled by the user, since we aren't taking into account the retry header in this retry implementation what do you think about treating all 4** responses the same way?

Suggested change

const retryable = status === 429 || status >= 500;

const wrapped = httpErrorWithOriginal(error);

throw retryable ? wrapped : new AbortError(wrapped);

const wrapped = httpErrorWithOriginal(error);

throw status >= 500 ? wrapped : new AbortError(wrapped);

@WilliamBergamin Ah I'm learning more about HTTP! Thanks for sharing this!

We're landing a change in 3d9a0af to save retries for server errors at this time. I agree it'd be alright to wait for feedback before extending this more.

The webhook clients have no request queue to honor a Retry-After header, so a 429 cannot respect the server's backoff on retry. Treat all 4xx responses uniformly and leave rate-limit handling to the caller; only 5xx responses are retried. Addresses review feedback on #2641. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

The webhook clients have no request queue to honor a Retry-After header, so a 429 cannot respect the server's backoff on retry. Treat all 4xx responses uniformly and leave rate-limit handling to the caller; only 5xx responses are retried. Addresses review feedback on #2641. Co-Authored-By: William Bergamin <25348381+WilliamBergamin@users.noreply.github.com> Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

…etry Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg

🔭 Duplicated comments from changed code!

zimeg · 2026-07-07T20:07:24Z


 export { addAppMetadata } from './instrument';

+export { default as retryPolicies, RetryOptions } from './retry-policies';


🎁 note: Here we match the export pattern of the @slack/web-api package:

node-slack-sdk/packages/web-api/src/index.ts

Line 17 in b0e335b

export { default as retryPolicies, RetryOptions } from './retry-policies';

…webhook-retries

…webhook-retries # Conflicts: # packages/webhook/src/WebhookTrigger.test.ts

…webhook-retries # Conflicts: # packages/webhook/src/WebhookTrigger.ts

zimeg added 3 commits July 2, 2026 01:43

feat(webhook): add retry policies mirroring @slack/web-api

a0e3e1d

feat(webhook): add opt-in retries to WebhookTrigger

a0e845e

feat(webhook): add opt-in retries to IncomingWebhook

4f0f591

zimeg added semver:minor enhancement M-T: A feature request for new functionality pkg:webhook applies to `@slack/webhook` labels Jul 2, 2026

zimeg self-assigned this Jul 2, 2026

zimeg and others added 8 commits July 2, 2026 02:25

refactor(webhook): order retryConfig before timeout in default args

ef40e60

feat(webhook): make WebhookTrigger.send payload optional

7c8e9ca

Default the payload to an empty object so send() can be called with no arguments, POSTing an empty body. send({}) continues to work unchanged. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Merge remote-tracking branch 'origin/eden/webhook-trigger' into eden/…

a4982fc

…webhook-retries # Conflicts: # packages/webhook/src/WebhookTrigger.ts

docs(webhook): revert send @param comment to original wording

74f0dcd

The `= {}` default now lives in the WebhookTrigger PR; keep the @param description unchanged here. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

fix(webhook): reject empty URL in WebhookTrigger constructor

700af6a

Use a falsy check so an empty-string URL is rejected up front rather than failing later at request time. Adds a guard test. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

docs(webhook): drop retry-classification comment from send()

817cfd0

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Merge branch 'eden/webhook-trigger' into eden/webhook-retries

38a310a

docs(webhook): add changeset for opt-in retries

345ff5b

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg marked this pull request as ready for review July 3, 2026 19:55

zimeg requested a review from a team as a code owner July 3, 2026 19:55

zimeg commented Jul 3, 2026

View reviewed changes

zimeg added this to the webhook@next milestone Jul 3, 2026

WilliamBergamin requested changes Jul 6, 2026

View reviewed changes

zimeg force-pushed the eden/webhook-retries branch from 56cf76e to 3d9a0af Compare July 6, 2026 22:44

zimeg and others added 2 commits July 6, 2026 23:47

chore: release webhook@7.2.0-rc.1

a2868ad

refactor(webhook): export retryPolicies as default namespace, pin p-r…

ee7f29f

…etry Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg commented Jul 7, 2026

View reviewed changes

zimeg added 4 commits July 7, 2026 13:10

chore: release webhook@7.2.0-rc.2

fce391b

Merge remote-tracking branch 'origin/eden/webhook-trigger' into eden/…

4e0f4f5

…webhook-retries

Merge remote-tracking branch 'origin/eden/webhook-trigger' into eden/…

839751b

…webhook-retries # Conflicts: # packages/webhook/src/WebhookTrigger.test.ts

Merge remote-tracking branch 'origin/eden/webhook-trigger' into eden/…

692179f

…webhook-retries # Conflicts: # packages/webhook/src/WebhookTrigger.ts


		export { addAppMetadata } from './instrument';

		export { default as retryPolicies, RetryOptions } from './retry-policies';

Uh oh!

Conversation

zimeg commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Requirements

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

zimeg Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

zimeg Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

zimeg Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

WilliamBergamin Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

zimeg Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zimeg Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zimeg commented Jul 2, 2026 •

edited

Loading

changeset-bot Bot commented Jul 2, 2026 •

edited

Loading

codecov Bot commented Jul 2, 2026 •

edited

Loading

zimeg Jul 6, 2026 •

edited

Loading