feat(webhook): add WebhookTrigger class for Workflow Builder triggers by zimeg · Pull Request #2615 · slackapi/node-slack-sdk

zimeg · 2026-06-02T21:17:39Z

Summary

This pull request adds a minimal WebhookTrigger class to @slack/webhook for Workflow Builder webhook triggers.

The package previously only supported incoming webhooks (IncomingWebhook). Workflow Builder triggers accept arbitrary JSON payloads and return JSON responses, so consumers like slack-github-action currently fall back to raw fetch.

The implementation is intentionally small and mirrors IncomingWebhook:

Constructor takes a URL and optional defaults (timeout, agent); rejects a missing or empty URL.
send(payload?) POSTs the payload (defaults to {}) and resolves to the parsed JSON response body (WebhookTriggerResult, typed { ok, error? }); HTTP and request failures reject.
Reuses the existing error infrastructure and User-Agent instrumentation, adding WebhookTrigger-named error types.

Notes for reviewers

URL guard: the constructor uses a falsy check (!url), so it rejects an empty string as well as undefined. This intentionally differs from IncomingWebhook, which only guards undefined.
Result typing: WebhookTriggerResult is typed closed as { ok: boolean; error?: string } — matching what the trigger endpoint returns ({ ok: true } or { ok: false, error }). Widening this later is backward-compatible; tightening a released open type would not be.

Preview

🔗 https://github.com/slackapi/node-slack-sdk/tree/eden/webhook-trigger/packages/webhook#trigger-a-workflow-builder-workflow

const { WebhookTrigger } = require('@slack/webhook');
const url = process.env.SLACK_WEBHOOK_TRIGGER_URL;

const trigger = new WebhookTrigger(url);

(async () => {
  // Keys should match the variables your workflow expects
  const result = await trigger.send({
    customer_name: 'Ada Lovelace',
    order_id: '1024',
  });
})();

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.

Add a new WebhookTrigger class that mirrors IncomingWebhook but handles Workflow Builder webhook triggers which return JSON responses with arbitrary payloads (vs plain text "ok" from incoming webhooks). - Constructor takes URL + defaults (timeout, agent) — same pattern - send() accepts arbitrary key-value payload, returns { ok, body } - Reuses existing error infrastructure and User-Agent instrumentation - Enables consumers like slack-github-action to use the SDK instead of raw fetch for WFB triggers Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

changeset-bot · 2026-06-02T21:17:46Z

🦋 Changeset detected

Latest commit: 5ddeb03

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-06-02T21:19:29Z

Codecov Report

❌ Patch coverage is 93.45794% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.97%. Comparing base (b0e335b) to head (5ddeb03).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2615      +/-   ##
==========================================
+ Coverage   88.90%   88.97%   +0.06%     
==========================================
  Files          63       64       +1     
  Lines       10256    10363     +107     
  Branches      452      467      +15     
==========================================
+ Hits         9118     9220     +102     
- Misses       1117     1122       +5     
  Partials       21       21

Flag	Coverage Δ
cli-hooks	`88.97% <93.45%> (+0.06%)`	⬆️
cli-test	`88.97% <93.45%> (+0.06%)`	⬆️
logger	`88.97% <93.45%> (+0.06%)`	⬆️
oauth	`88.97% <93.45%> (+0.06%)`	⬆️
socket-mode	`88.97% <93.45%> (+0.06%)`	⬆️
web-api	`88.97% <93.45%> (+0.06%)`	⬆️
webhook	`88.97% <93.45%> (+0.06%)`	⬆️

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.

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

Workflow Builder webhook trigger inputs are always string values. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

WilliamBergamin

Gave this a quick look and it looks good 💯

if we need to dry this up in the future we can look into it at that time

# Conflicts: # packages/webhook/package.json # packages/webhook/src/index.ts

Allow send() to be called with no arguments, POSTing an empty body. send({}) continues to work unchanged. 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>

…s test Add a test that a 401 with { ok: false, error: 'invalid_auth' } rejects with an HTTPError exposing the response status and body. Remove the success test asserting workflow_run_id so success cases only assert result.ok === true. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

WebhookTrigger throws the same coded errors as IncomingWebhook but had no correspondingly named types. Add WebhookTriggerSendError / WebhookTriggerHTTPError / WebhookTriggerRequestError aliases and export them so consumers have properly-named errors to catch. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

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

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

Coerce result.ok from body.ok instead of defaulting a missing field to true, so only an explicit ok:true reports success. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg

🗣️ Words I think for the readers and reviewers!

zimeg · 2026-07-03T19:20:48Z

 }

 export type IncomingWebhookSendError = IncomingWebhookRequestError | IncomingWebhookHTTPError;
+export type WebhookTriggerSendError = WebhookTriggerRequestError | WebhookTriggerHTTPError;


⚠️ note: The error handling is shared between webhook techniques but so we export these values under a similar namespace.

zimeg · 2026-07-03T19:41:25Z

+   * Processes an HTTP response into a WebhookTriggerResult.
+   */
+  private buildResult(response: AxiosResponse): WebhookTriggerResult {
+    const body = typeof response.data === 'string' ? JSON.parse(response.data) : response.data;


🔬 note: This feels defensive to me and might be removed as response is unpacked to match standard "fetch"!

WilliamBergamin

Nice work 💯

Left one comment on test coverage but its possible my comment is redundent

WilliamBergamin · 2026-07-03T20:03:15Z

  code: ErrorCode.RequestError;
  original: Error;
 }
+export type WebhookTriggerRequestError = IncomingWebhookRequestError;


Safe move 🧠 I like it 💯

WilliamBergamin · 2026-07-03T20:08:25Z

+      });
+    });
+
+    describe('User-Agent header', () => {


Nice 💯

should we also add a tests that covers using addAppMetadata to expand the user-agent value?

@WilliamBergamin Thanks for calling this out! We're introducing a test in 3bed3dc for this.

WilliamBergamin · 2026-07-03T20:09:02Z

+ * A client for Slack's Workflow Builder webhook triggers
+ * @see {@link https://slack.com/help/articles/360041352714-Build-a-workflow--Create-a-workflow-that-starts-outside-of-Slack}
+ */
+export class WebhookTrigger {


Paise for mirroring existing behaviors 💯

Drop the { ok, body } wrapper so send() resolves to the parsed response body itself, exposing ok/error without nesting or a duplicated ok field. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Assert that metadata added via addAppMetadata is sent in the User-Agent header on a WebhookTrigger request, alongside the base webhook agent. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

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

send() now returns response.data directly; the string-vs-object parse branch was dead code since axios already parses JSON responses. Removes the now-unused AxiosResponse import. Simplifies the eventual fetch swap. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

The trigger endpoint responds with { ok: true } or { ok: false, error }, so type the result closed rather than an open index signature. Widening later is backward-compatible; tightening a released `any` would not be. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

The package now covers both Incoming Webhooks and Workflow Builder triggers, so the narrower "Incoming Webhooks" title is outdated. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

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

zimeg

🔏 A few more comments of confidence!

zimeg · 2026-07-07T23:03:04Z

+      });
+    });
+
+    describe('User-Agent header', () => {


@WilliamBergamin Thanks for calling this out! We're introducing a test in 3bed3dc for this.

zimeg · 2026-07-08T13:00:25Z

+  public async send(payload: WebhookTriggerSendArguments = {}): Promise<WebhookTriggerResult> {
+    try {
+      const response = await this.axios.post(this.url, payload);
+      return response.data;
+      // biome-ignore lint/suspicious/noExplicitAny: errors can be anything
+    } catch (error: any) {
+      if (error.response !== undefined) {
+        throw httpErrorWithOriginal(error);
+      }
+      if (error.request !== undefined) {
+        throw requestErrorWithOriginal(error);
+      }
+      throw error;
+    }
+  }
+}


👁️‍🗨️ note: Our return inlines the response values without more change to mirror implementations of the @slack/web-api package a bit more!

zimeg · 2026-07-08T13:00:43Z

+export interface WebhookTriggerResult {
+  ok: boolean;
+  error?: string;
+}


🪬 note: These values are more strict now too!

This looks good 💯

If we need to add more fields in the future we can

zimeg · 2026-07-08T13:02:10Z

📚 note: I hoped to generalize this package README for now with added information but think we might revise this ongoing?

WilliamBergamin

Ship it 🚀

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

+export interface WebhookTriggerResult {
+  ok: boolean;
+  error?: string;
+}


This looks good 💯

If we need to add more fields in the future we can

zimeg · 2026-07-08T17:47:27Z

@WilliamBergamin So exciting! Thanks for sharing big ideas and kind thoughts toward this 🧠 💡

Bring the new @slack/webhook features from main into v8: - WebhookTrigger class for Workflow Builder triggers (#2615) - opt-in retries for IncomingWebhook and WebhookTrigger (#2641) Re-expressed on v8's fetch + Error-subclass architecture (main built them on axios + error-factory functions). Non-webhook release churn from main's parallel 7.x line (docs, web-api version bumps, CHANGELOGs) resolved to v8. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg and others added 2 commits June 2, 2026 14:20

docs(webhook): update WebhookTrigger @see link to JSODC article

89c7af2

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

fix(webhook): constrain WebhookTriggerSendArguments values to string

0aab45b

Workflow Builder webhook trigger inputs are always string values. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

WilliamBergamin approved these changes Jun 29, 2026

View reviewed changes

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

2dcef0f

# Conflicts: # packages/webhook/package.json # packages/webhook/src/index.ts

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

zimeg self-assigned this Jun 30, 2026

zimeg added the javascript Pull requests that update Javascript code label Jun 30, 2026

zimeg modified the milestones: webhook@next, webhook@7.1.0 Jun 30, 2026

zimeg mentioned this pull request Jul 2, 2026

feat(webhook): add opt-in retries to IncomingWebhook and WebhookTrigger #2641

Merged

2 tasks

zimeg and others added 12 commits July 3, 2026 10:05

feat(webhook): default WebhookTrigger.send payload to empty object

29ea38e

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

fix(webhook): reject empty URL in WebhookTrigger constructor

d6677bf

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>

refactor(webhook): colocate each WebhookTrigger error alias with its …

cd50095

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

test(webhook): group WebhookTrigger send() tests by success and failure

2724cd7

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

test(webhook): assert send() transmits the payload body

b8992d8

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

docs(webhook): add WebhookTrigger changeset and README usage example

eab95b3

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

docs: readme

ceba283

docs: readme

eace3ba

docs: readme

b02a78e

fix(webhook): derive WebhookTrigger result ok strictly from the body

e3626f9

Coerce result.ok from body.ok instead of defaulting a missing field to true, so only an explicit ok:true reports success. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

zimeg commented Jul 3, 2026

View reviewed changes

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

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

Merge branch 'main' into eden/webhook-trigger

7968168

WilliamBergamin approved these changes Jul 3, 2026

View reviewed changes

zimeg and others added 8 commits July 7, 2026 13:54

refactor(webhook): return the trigger response body directly from send()

dc3dc2d

Drop the { ok, body } wrapper so send() resolves to the parsed response body itself, exposing ok/error without nesting or a duplicated ok field. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

test(webhook): verify addAppMetadata expands WebhookTrigger User-Agent

3bed3dc

Assert that metadata added via addAppMetadata is sent in the User-Agent header on a WebhookTrigger request, alongside the base webhook agent. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

test(webhook): drop explanatory comment from addAppMetadata UA test

c0f5c7e

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

docs(webhook): retitle README to Slack Webhooks

1684fa8

The package now covers both Incoming Webhooks and Workflow Builder triggers, so the narrower "Incoming Webhooks" title is outdated. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

docs(webhook): use singular Slack Webhook README title

edd3ecb

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

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

5ddeb03

zimeg commented Jul 8, 2026

View reviewed changes

zimeg removed the javascript Pull requests that update Javascript code label Jul 8, 2026

WilliamBergamin approved these changes Jul 8, 2026

View reviewed changes

zimeg merged commit a5bd5c8 into main Jul 8, 2026
14 checks passed

zimeg deleted the eden/webhook-trigger branch July 8, 2026 17:48

Uh oh!

Conversation

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

Uh oh!

Summary

Notes for reviewers

Preview

Requirements

Uh oh!

changeset-bot Bot commented Jun 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 Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg commented Jul 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zimeg commented Jun 2, 2026 •

edited

Loading

changeset-bot Bot commented Jun 2, 2026 •

edited

Loading

codecov Bot commented Jun 2, 2026 •

edited

Loading

WilliamBergamin left a comment •

edited

Loading