Flowlib Docs

The webhooks plugin adds inbound webhook support — external services can trigger flow runs by making HTTP requests to unique webhook URLs.

Installation

pnpm add @flowlib/webhooks

npm install @flowlib/webhooks

yarn add @flowlib/webhooks

bun add @flowlib/webhooks

Setup

flowlib.config.ts

import { webhooks } from '@flowlib/webhooks';

export const flowlibConfig = defineConfig({
  // ...
  plugins: [
    webhooks({
      webhookBaseUrl: 'https://api.myapp.com/flowlib',
    }),
  ],
});

The webhookBaseUrl is the public URL prefix used to generate webhook URLs displayed in the editor. Set this to your production URL so webhook URLs are correct.

Options

Option	Type	Default	Description
`webhookBaseUrl`	`string`	—	Public URL prefix for generated webhook URLs.
`rateLimitMaxRequests`	`number`	`60`	Maximum requests per rate limit window.
`rateLimitWindowMs`	`number`	`60000` (1 min)	Rate limit window duration in milliseconds.
`dedupTtlMs`	`number`	`86400000` (24h)	Time-to-live for deduplication of repeated requests.

Regenerate the schema to add the webhook tables:

npx flowlib-cli generate
npx flowlib-cli migrate --push

How it works

Add a Trigger: Webhook node to a flow. The plugin generates a unique URL for that trigger. When an external service sends a request to that URL, the flow runs with the request body as input.

The webhook URL format: {webhookBaseUrl}/webhooks/{webhookId}

Managing webhooks

Webhooks are managed through the trigger system:

GET /flows/:flowId/triggers — lists all triggers including webhooks
POST /flows/:flowId/triggers — create a new webhook trigger
DELETE /triggers/:triggerId — delete a webhook trigger

Each webhook has a unique ID and optional secret for signature verification.

Security features

The plugin includes built-in protection for webhook endpoints:

Signature verification — validate HMAC signatures from webhook providers (GitHub, Slack, etc.) to ensure requests are authentic
Rate limiting — configurable per-endpoint rate limits to prevent abuse
Deduplication — repeated requests with the same payload are deduplicated within the TTL window