qhook

Lightweight workflow engine with built-in queue and retry. Receive webhooks and API events, execute HTTP actions reliably — single binary, zero infrastructure.

Documentation | Examples | Why qhook?

What qhook Does

1. Receive events from two entry points:
   • Webhooks (external) — Stripe, GitHub, PagerDuty, etc. with signature verification
   • API (internal) — your apps, IDP, CI/CD trigger events via POST /events/{source}/{event_type} (or POST /events/{event_type} with default source)
2. Execute HTTP actions reliably — one call or a multi-step pipeline
3. Handle failures — retry, error routing, rollback, Dead Letter Queue

Simple:                           Multi-step:
  event → POST /billing             event → build → deploy → notify
  (with retry + DLQ)                             ↓ fail
                                             rollback → alert

Why qhook?

• Zero infrastructure. Single binary, SQLite for dev, Postgres for production. No Redis, no message broker.
• Webhook verification built in. GitHub, Stripe, Shopify, PagerDuty, Grafana, Terraform Cloud, GitLab, HMAC, AWS SNS X.509.
• From one action to a pipeline. Start with a single HTTP call; grow into multi-step workflows with branching, parallelism, and rollback — same YAML, same engine.
• Production ready. Prometheus metrics, health checks, Slack/Discord alerts, rate limiting, circuit breaker, OpenTelemetry tracing, structured logging.

See Why qhook? for detailed comparisons and use cases.

Quick Start

cargo install qhook
# Or: docker run -p 8888:8888 -v $(pwd)/qhook.yaml:/data/qhook.yaml ghcr.io/totte-dev/qhook

Simple: one event, one action

# qhook.yaml
database:
  driver: sqlite

sources:
  github:
    type: webhook
    verify: github
    secret: ${GITHUB_WEBHOOK_SECRET}

handlers:
  deploy:
    source: github
    events: [push]
    url: http://deployer:3000/deploy
    filter: "$.ref == refs/heads/main"
    retry: { max: 5 }

Multi-step: event triggers a pipeline

workflows:
  deploy-pipeline:
    source: github
    events: [push]
    timeout: 600
    steps:
      - name: build
        url: http://ci:3000/build
        retry: { max: 2, errors: [5xx, timeout] }
      - name: deploy-staging
        url: http://deployer:3000/deploy
        catch:
          - errors: [all]
            goto: rollback
      - name: smoke-test
        url: http://tester:3000/smoke
        catch:
          - errors: [all]
            goto: rollback
      - name: deploy-prod
        url: http://deployer:3000/deploy
        end: true
      - name: rollback
        url: http://deployer:3000/rollback
        end: true

qhook start

See the Getting Started guide for a full walkthrough.

Step Types

See the Workflows guide for details.

Installation

cargo install qhook                    # From crates.io
docker pull ghcr.io/totte-dev/qhook    # Docker image

Or build from source:

git clone https://github.com/totte-dev/qhook.git && cd qhook
cargo build --release

CLI

qhook start                        # Start server
qhook init                         # Generate default config
qhook validate                     # Validate config
qhook jobs list --status dead      # List dead-letter jobs
qhook jobs retry                   # Retry all dead jobs
qhook start --env production       # Config overlay (merges qhook.production.yaml)
qhook tail                         # Stream events and jobs in real time
qhook export events > events.jsonl # Export events as JSONL
qhook events list                  # List received events
qhook events replay --source stripe # Replay events for matching handlers
qhook workflow-runs list           # List workflow runs
qhook workflow-runs redrive <ID>   # Redrive a failed workflow

See the CLI Reference for all commands.

Management API

Track events and jobs programmatically:

# Send an event with explicit source name
curl -X POST http://localhost:8888/events/platform/deploy.start \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"service": "api", "version": "1.2.3"}'
# → {"event_id": "01J...", "jobs_created": 2}

# The old route still works (defaults to source "app")
# curl -X POST http://localhost:8888/events/deploy.start ...

# Check event status
curl http://localhost:8888/api/events/01J... -H "Authorization: Bearer $TOKEN"
# → {jobs: [{status: "completed"}, {status: "running"}], ...}

# Check job details
curl http://localhost:8888/api/jobs/01J...?include_attempts=true -H "Authorization: Bearer $TOKEN"

Any frontend — Backstage, Retool, or custom dashboards — can consume this API.

Documentation

Full documentation at totte-dev.github.io/qhook.

Examples

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.