hookdeck-deploy-cli

README

@toppy/hookdeck-deploy-cli

Deploy Hookdeck webhook infrastructure from declarative manifest files.

Define your sources, destinations, connections, and transformations in hookdeck.jsonc files, then deploy them with a single command. Supports environment overlays, manifest inheritance, drift detection, and variable interpolation.

Install

npm install -D @toppy/hookdeck-deploy-cli

or

pnpm add -D @toppy/hookdeck-deploy-cli

The package includes prebuilt binaries for Linux, macOS, and Windows (amd64/arm64). No build tools required.

Authentication

Profiles (recommended)

Authenticate using the Hookdeck CLI:

hookdeck login

This creates a config file at ~/.config/hookdeck/config.toml with your API key. For multi-environment setups, add named profiles:

profile = "default"

[default]
api_key = "hk_..."

[staging]
api_key = "hk_..."
project_id = "prj_..."

[production]
api_key = "hk_..."
project_id = "prj_..."

Reference profiles in your manifest:

{
  "env": {
    "staging": { "profile": "staging" },
    "production": { "profile": "production" }
  }
}

Environment variable

For CI/CD pipelines, set HOOKDECK_API_KEY. This takes priority over profile-based credentials:

HOOKDECK_API_KEY=hk_... hookdeck-deploy deploy --env production

Resolution order

1. HOOKDECK_API_KEY environment variable
2. Named profile from manifest's env.<name>.profile
3. Default profile from config file

Config file locations (checked in order):

• .hookdeck/config.toml (project-local)
• ~/.config/hookdeck/config.toml (global)

Quick Start

1. Create a manifest file (hookdeck.jsonc):

{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json",
  "destination": {
    "name": "my-service",
    "url": "https://my-service.example.com/webhooks"
  }
}

2. Preview changes with a dry run:

hookdeck-deploy deploy --dry-run

3. Deploy:

hookdeck-deploy deploy

Resources are deployed in dependency order: source -> transformation -> destination -> connection.

Manifest Guide

Sources

Define a Hookdeck source to receive webhooks:

{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json",
  "source": {
    "name": "my-webhook-source",
    "description": "Receives order webhooks from external service"
  }
}

After deploying, the source URL from Hookdeck is automatically synced back to your wrangler.jsonc (disable with --sync-wrangler=false).

Destinations

Define where events are delivered:

{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json",
  "destination": {
    "name": "order-processor",
    "url": "https://order-processor.example.com/webhooks",
    "rate_limit": 1,
    "rate_limit_period": "concurrent"
  }
}

Connections

Wire a source to a destination with optional filtering:

{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json",
  "destination": {
    "name": "order-processor",
    "url": "https://order-processor.example.com/webhooks"
  },
  "env": {
    "staging": {
      "connection": {
        "name": "orders-to-processor",
        "source": "order-source",
        "filter": {
          "type": "order.created"
        }
      }
    }
  }
}

Connections reference sources and destinations by name. The filter shorthand is converted to a filter rule during deploy. You can also reference transformations:

"connection": {
  "name": "orders-to-processor",
  "source": "order-source",
  "transformations": ["enrich-order"]
}

Transformations

Transformations use a separate schema and manifest structure:

{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-transformation.schema.json",
  "transformation": {
    "name": "enrich-order",
    "description": "Adds computed fields to order payload",
    "env": {
      "API_BASE_URL": "https://api.example.com"
    }
  }
}

Inheritance

Use extends to share configuration across manifests. A common pattern is a root manifest that defines environment profiles:

// Root hookdeck.jsonc
{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json",
  "env": {
    "staging": { "profile": "staging" },
    "production": { "profile": "production" }
  }
}

// services/my-service/hookdeck.jsonc
{
  "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json",
  "extends": "../../hookdeck.jsonc",
  "destination": {
    "name": "my-service",
    "url": "https://my-service-dev.example.com"
  },
  "env": {
    "staging": {
      "destination": {
        "url": "https://my-service-staging.example.com"
      }
    },
    "production": {
      "destination": {
        "url": "https://my-service-production.example.com"
      }
    }
  }
}

Child manifests inherit all fields from the parent. Environment-specific overrides are merged on top.

Environment Overrides

Deploy to specific environments with --env:

hookdeck-deploy deploy --env staging
hookdeck-deploy deploy --env production

The env object in the manifest defines per-environment overrides for any resource field:

{
  "destination": {
    "name": "my-service",
    "url": "https://my-service-dev.example.com"
  },
  "env": {
    "staging": {
      "destination": { "url": "https://my-service-staging.example.com" }
    },
    "production": {
      "destination": { "url": "https://my-service-production.example.com" }
    }
  }
}

Without --env, the base values are used (useful for local development).

Variable Interpolation

Reference environment variables in manifest values with ${VAR_NAME}:

{
  "destination": {
    "name": "my-service",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {
      "webhook_secret_key": "${HOOKDECK_SIGNING_SECRET}"
    }
  }
}

Variables are resolved from the process environment at deploy time.

CLI Reference

Commands

Command	Description
hookdeck-deploy deploy	Upsert resources in dependency order (source -> transformation -> destination -> connection)
hookdeck-deploy drift	Compare manifest against live Hookdeck state, report missing or drifted resources
hookdeck-deploy status	Show whether each manifest resource exists on Hookdeck with name, ID, and URL
hookdeck-deploy schema [type]	Output JSON schema for manifest files (deploy or transformation)

Global Flags

Flag	Short	Description
--file <path>	-f	Manifest file path (default: hookdeck.jsonc or hookdeck.json)
--env <name>	-e	Environment overlay (e.g., staging, production)
--dry-run		Preview changes without applying
--profile <name>		Override credential profile

Deploy Flags

Flag	Description
--sync-wrangler	Sync source URL back to wrangler.jsonc after deploy (default: true)

JSON Schemas

Add a $schema property to your manifest for IDE autocompletion and validation:

// For sources, destinations, and connections:
{ "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-deploy.schema.json" }

// For standalone transformations:
{ "$schema": "node_modules/@toppy/hookdeck-deploy-cli/schemas/hookdeck-transformation.schema.json" }

Contributing

Prerequisites

• Go 1.24+

Getting Started

git clone https://github.com/toppynl/hookdeck-deploy-cli.git
cd hookdeck-deploy-cli
go build -o hookdeck-deploy-cli .
go test ./...

Build

go build -o hookdeck-deploy-cli .

Test

go test ./...

License

MIT