Webhook Trigger

The Webhook trigger is a specialized HTTP trigger designed to handle webhooks from various providers. It includes built-in support for signature verification and replay attack prevention.

Installation

pnpm add @stepflowjs/trigger-webhook

Usage

import { WebhookTrigger } from "@stepflowjs/trigger-webhook";

const trigger = new WebhookTrigger({
  path: "/webhooks/github",
  secret: process.env.GITHUB_WEBHOOK_SECRET,
  signatureHeader: "x-hub-signature-256",
  algorithm: "sha256",
  signaturePrefix: "sha256=",
});

await trigger.start(async (event) => {
  await stepflow.trigger("github-event", event.data);
});

Provider Presets

While WebhookTrigger is generic, here are common configurations for popular providers:

GitHub

const githubTrigger = new WebhookTrigger({
  path: "/webhooks/github",
  secret: process.env.GITHUB_WEBHOOK_SECRET,
  signatureHeader: "x-hub-signature-256",
  algorithm: "sha256",
  signaturePrefix: "sha256=",
});

Stripe

const stripeTrigger = new WebhookTrigger({
  path: "/webhooks/stripe",
  secret: process.env.STRIPE_WEBHOOK_SECRET,
  signatureHeader: "stripe-signature",
  algorithm: "sha256",
  timestampHeader: "stripe-signature", // Stripe includes timestamp in the signature header
  timestampTolerance: 300,
});

Slack

const slackTrigger = new WebhookTrigger({
  path: "/webhooks/slack",
  secret: process.env.SLACK_SIGNING_SECRET,
  signatureHeader: "x-slack-signature",
  algorithm: "sha256",
  signaturePrefix: "v0=",
  timestampHeader: "x-slack-request-timestamp",
});

Shopify

const shopifyTrigger = new WebhookTrigger({
  path: "/webhooks/shopify",
  secret: process.env.SHOPIFY_API_SECRET,
  signatureHeader: "x-shopify-hmac-sha256",
  algorithm: "sha256",
});

Twilio

const twilioTrigger = new WebhookTrigger({
  path: "/webhooks/twilio",
  secret: process.env.TWILIO_AUTH_TOKEN,
  signatureHeader: "x-twilio-signature",
  algorithm: "sha1",
});

Configuration

Option	Type	Default	Description
`path`	`string`	required	The webhook endpoint path
`secret`	`string`	required	Secret for signature verification
`signatureHeader`	`string`	`x-webhook-signature`	Header name containing the signature
`algorithm`	`string`	`sha256`	Signing algorithm (`sha256`, `sha1`, `sha512`)
`signaturePrefix`	`string`	`undefined`	Signature prefix like `sha256=`
`timestampHeader`	`string`	`undefined`	Header name for timestamp (replay prevention)
`timestampTolerance`	`number`	`300`	Maximum age in seconds for timestamp validation

Webhook Trigger

On this page