# Webhooks (/docs/plugins/webhooks)





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

## Installation [#installation]

<Tabs items="['pnpm', 'npm', 'yarn', 'bun']">
  <Tab value="pnpm">
    ```bash
    pnpm add @flowlib/webhooks
    ```
  </Tab>

  <Tab value="npm">
    ```bash
    npm install @flowlib/webhooks
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @flowlib/webhooks
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @flowlib/webhooks
    ```
  </Tab>
</Tabs>

## Setup [#setup]

```ts title="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 [#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:

```bash
npx flowlib-cli generate
npx flowlib-cli migrate --push
```

## How it works [#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 [#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 [#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