hookpipe

Self-hosted webhook relay with transform pipelines. Receive webhooks, authenticate, filter, transform, and deliver to one or more destinations. Built for self-hosted environments where you control the infrastructure.

Quick Start — Docker

docker build -t hookpipe -f docker/Dockerfile .
docker run -p 3000:3000 -v ./pipelines:/app/pipelines -v ./data:/app/data hookpipe

Quick Start — Bare Metal

npm install
cp .env.example .env
mkdir -p pipelines data
node src/cli/index.js serve

Webhooks are received at POST /hook/:pipeline-id.

Pipeline YAML Schema

Pipelines are YAML files in the pipelines/ directory. Each file defines one pipeline.

Required Fields

Field	Type	Description
id	string	Unique pipeline identifier (must match filename)
destinations	array	One or more delivery targets

Each destination requires:

Field	Type	Description
id	string	Unique destination identifier within the pipeline
type	string	Destination type (http)
url	string	Target URL

Optional Fields

Field	Type	Description
name	string	Human-readable pipeline name
description	string	Pipeline description
auth	object	Authentication configuration
filter	string	Filter plugin name
filter_config	object	Config passed to the filter plugin
transform	string	Transform plugin name
retry	object	Retry policy override

Auth Configuration

Field	Type	Description
type	string	hmac-sha256 or hmac-sha1
secret	string	HMAC secret (supports ${ENV_VAR} interpolation)
header	string	Header containing the signature

Destination Options

Field	Type	Description
method	string	HTTP method (default: POST)
headers	object	Additional headers to send
body_template	string	Handlebars template for the request body
timeout_ms	number	Request timeout in milliseconds
on_failure	string	Failure behavior (retry or log)

Complete Example

id: github-deploy
name: GitHub Deploy Notifications
description: Forward GitHub push events to deploy service

auth:
  type: hmac-sha256
  secret: ${GITHUB_WEBHOOK_SECRET}
  header: x-hub-signature-256

filter: github-event-filter
filter_config:
  events:
    - push
    - release

transform: extract-commit-info

destinations:
  - id: deploy-service
    type: http
    url: https://deploy.internal/api/trigger
    method: POST
    headers:
      authorization: Bearer ${DEPLOY_TOKEN}
    timeout_ms: 10000
    on_failure: retry

  - id: slack-notify
    type: http
    url: https://hooks.slack.com/services/T00/B00/xxx
    body_template: |
      {"text": "Deploy triggered by {{payload.pusher.name}} on {{payload.ref}}"}
    on_failure: log

retry:
  maxAttempts: 5
  backoff: exponential
  initialDelayMs: 2000
  maxDelayMs: 300000

Plugin API

Plugins are CommonJS modules loaded via createRequire (the project itself is ESM). Place them in the plugins/ directory.

Transform Plugin

// plugins/extract-commit-info.cjs
module.exports.transform = function (payload, headers, config) {
  // Return transformed payload object
  // Return null to drop the webhook entirely
  return {
    ref: payload.ref,
    commits: payload.commits.map(c => c.message),
    pusher: payload.pusher.name,
  };
};

Signature: transform(payload, headers, config) → object | null

• payload — parsed JSON body of the incoming webhook
• headers — request headers (lowercased keys)
• config — the pipeline's filter_config object (shared namespace)
• Returns the transformed payload, or null to drop the webhook

Filter Plugin

// plugins/github-event-filter.cjs
module.exports.filter = function (payload, headers, config) {
  const event = headers['x-github-event'];
  if (config.events.includes(event)) {
    return { pass: true };
  }
  return { pass: false, reason: `Event '${event}' not in allowed list` };
};

Signature: filter(payload, headers, config) → { pass: boolean, reason?: string }

• Return { pass: true } to continue processing
• Return { pass: false, reason: "..." } to reject the webhook

CLI Reference

hookpipe <command> [options]

hookpipe serve

Start the webhook server.

Flag	Description
-p, --port <number>	Port to listen on
-H, --host <string>	Host to bind to
-c, --config <path>	Config file path
--pipelines <dir>	Pipelines directory
--plugins <dir>	Plugins directory

hookpipe test <pipeline-id>

Dry-run a webhook through a pipeline without delivering.

Flag	Description
-f, --file <path>	JSON file to use as payload
-d, --data <json>	Inline JSON payload
--header <header>	Custom header (repeatable, format: Key: Value)
--skip-auth	Skip HMAC authentication check
-c, --config <path>	Config file path

hookpipe logs

Query delivery logs.

Flag	Description
--pipeline <id>	Filter by pipeline ID
--status <status>	Filter by status (success, failed, pending)
--since <duration>	Show logs since duration (e.g. 1h, 7d)
--limit <n>	Max number of entries (default: 50)
--json	Output as JSON

hookpipe replay <delivery-id>

Re-enqueue a previous delivery for reprocessing.

Flag	Description
--dry-run	Show what would be replayed without enqueuing
-c, --config <path>	Config file path

Configuration

hookpipe loads configuration from a YAML file, environment variables, and CLI flags.

Precedence (highest wins): CLI flags > environment variables > YAML file > defaults

Config File

By default, hookpipe looks for hookpipe.yaml in the working directory. Override with --config or HOOKPIPE_CONFIG.

host: 0.0.0.0
port: 3000

db:
  path: ./data/hookpipe.db

log:
  level: info

pipelines:
  dir: ./pipelines

plugins:
  dir: ./plugins

retry:
  maxAttempts: 3
  backoff: exponential
  initialDelayMs: 1000
  maxDelayMs: 300000

queue:
  pollIntervalMs: 1000
  concurrency: 5

Environment Variables

Variable	Maps to	Default
HOOKPIPE_PORT	port	3000
HOOKPIPE_HOST	host	0.0.0.0
HOOKPIPE_DB_PATH	db.path	./data/hookpipe.db
HOOKPIPE_LOG_LEVEL	log.level	info
HOOKPIPE_PIPELINES_DIR	pipelines.dir	./pipelines
HOOKPIPE_PLUGINS_DIR	plugins.dir	./plugins
HOOKPIPE_CONFIG	config file path	hookpipe.yaml

Pipeline YAML values support ${ENV_VAR} interpolation for secrets.

Trust Model

hookpipe v1.0 has no sandbox. Plugins are loaded as plain Node.js modules with full access to the process, filesystem, and network.

This is by design for self-hosted environments where you control what code runs on your infrastructure. The tradeoff is simplicity and zero overhead in exchange for requiring trust in your plugins.

Guidelines:

• Only load plugins you wrote or audited
• Do not accept plugin uploads from untrusted sources
• Run hookpipe with least-privilege OS permissions
• Use Docker to limit blast radius if needed

v1.1 will add optional isolation for plugins.

Tech Stack

Component	Role
Node.js 22+	Runtime
Fastify	HTTP server
better-sqlite3	Delivery queue and log storage
Commander.js	CLI framework
Pino	Structured logging
Handlebars	Body templates
chokidar	Pipeline hot-reload (file watching)

Roadmap

v1.0 — Core (current)

• Fastify HTTP server, YAML pipelines, env var interpolation
• HMAC-SHA256/SHA1/Stripe authentication
• JS transform + filter plugins (CJS, no sandbox)
• HTTP destination adapter with Handlebars templates
• SQLite delivery log, retry with exponential backoff, dead letter queue
• Pipeline hot-reload via chokidar
• CLI: serve, test, logs, replay
• Docker image

v1.1 — Agent Layer

• REST Admin API (CRUD pipelines, query logs, replay)
• Agent registration + scoped API keys
• Agent event queue (subscribe, poll, acknowledge)
• SSE real-time event stream
• Agent-writable transforms (runtime upload, sandboxed)
• Plugin sandbox (isolated-vm)
• Skills distribution via skills.sh

v1.2 — Polish

• Destinations: Telegram, Discord, Slack, SMTP, File
• Prometheus metrics endpoint
• Rate limiting per pipeline
• hookpipe init scaffolding
• hookpipe validate pipeline linting

v1.3 — Scale

• Redis/BullMQ queue backend
• Horizontal scaling (multiple workers)
• Pipeline chaining
• TypeScript plugin support

License

MIT