qhook

Lightweight event-to-action engine. Turn webhooks and API events into reliable HTTP actions — single binary, no Redis, no Kubernetes.

Documentation | Examples | Why qhook?

What qhook Does

1. Receive events — webhooks (with signature verification), AWS SNS, or internal API
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

Kubernetes is not required, but if you already run a cluster, a Helm chart is also available:

helm install qhook ./charts/qhook

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 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.

Documentation

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

Examples

License

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