hookdeck-manager

🔄 Hookdeck Manager CLI

A powerful CLI tool for managing your Hookdeck webhook infrastructure with ease.

📖 Table of Contents

• Overview
• Installation
• Authentication
• Commands at a Glance
• Sources Management
• Destinations Management
• Connections Management
• Interactive Connection Creation
• Shopify Webhook Integration
• Example Workflows
• Tips and Best Practices
• Troubleshooting
• Contributing
• License

🚀 Overview

The Hookdeck Manager CLI provides a powerful command-line interface for creating and managing your Hookdeck webhook infrastructure. It streamlines your workflow for handling sources (webhook endpoints), destinations (where webhooks are forwarded), and connections between them.

Key Features:

• 🔌 Create and manage webhook sources (Webhook, Shopify, GitHub, Stripe)
• 🎯 Set up diverse destinations (HTTP endpoints, CLI, Mock API)
• 🔄 Establish and configure connections with complex routing rules
• 🧩 Apply transformations, filters, retry logic, and delays to connections
• 🔮 Interactive mode for guided setup of complex resources
• 🛠️ Comprehensive command set for full infrastructure management

Whether you're a developer integrating webhook systems, a DevOps professional maintaining webhook infrastructure, or a solution architect designing resilient event flows, the Hookdeck Manager CLI puts everything at your fingertips.

📥 Installation

NPM

npm install -g hookdeck-manager

Yarn

yarn global add hookdeck-manager

From Source

git clone https://github.com/yourusername/hookdeck-manager.git
cd hookdeck-manager
npm install
npm run build
npm link

Verifying Installation

After installation, verify that the CLI is working correctly:

hookdeck-manager --version

This should display the current version of the Hookdeck Manager CLI.

🔑 Authentication

Before using the CLI, you need to authenticate with your Hookdeck API key.

Option 1: Environment Variable

export HOOKDECK_API_KEY=your_api_key
hookdeck-manager list-sources

Option 2: Command Line Parameter

hookdeck-manager --api-key=your_api_key list-sources

Option 3: Configuration

When you first run a command with the API key, it will be saved to your configuration file for future use:

hookdeck-manager --api-key=your_api_key list-sources
# For subsequent commands, you won't need to provide the API key again
hookdeck-manager list-destinations

🧭 Commands at a Glance

The CLI is organized into three main command groups:

Sources

# List all sources
hookdeck-manager list-sources

# Create a new source
hookdeck-manager create-source --name "My Webhook" --type WEBHOOK

# Get details of a specific source
hookdeck-manager get-source source_id

# Update a source
hookdeck-manager update-source source_id --name "Updated Name"

# Delete a source
hookdeck-manager delete-source source_id

Destinations

# List all destinations
hookdeck-manager list-destinations

# Create a new destination
hookdeck-manager create-destination --name "My API" --type HTTP --url "https://myapi.com/webhook"

# Get details of a specific destination
hookdeck-manager get-destination destination_id

# Update a destination
hookdeck-manager update-destination destination_id --name "Updated API"

# Delete a destination
hookdeck-manager delete-destination destination_id

Connections

# List all connections
hookdeck-manager list-connections

# Create a connection
hookdeck-manager create-connection --source-id src_123 --destination-id dest_456 --name "My Connection"

# Interactive connection creation (recommended for new users)
hookdeck-manager connect

# Get connection details
hookdeck-manager get-connection connection_id

# Update a connection
hookdeck-manager update-connection connection_id --name "Updated Connection"

# Pause/unpause a connection
hookdeck-manager pause-connection connection_id
hookdeck-manager unpause-connection connection_id

# Enable/disable a connection
hookdeck-manager enable-connection connection_id
hookdeck-manager disable-connection connection_id

# Delete a connection
hookdeck-manager delete-connection connection_id

📡 Sources Management

Sources in Hookdeck represent webhook endpoints that receive data from external services.

Types of Sources

• WEBHOOK: Standard HTTP webhook
• SHOPIFY: Shopify webhook
• GITHUB: GitHub webhook
• STRIPE: Stripe webhook

Creating a Source

hookdeck-manager create-source \
  --name "Payment Webhooks" \
  --type STRIPE \
  --description "Receives payment events from Stripe"

Authentication Options

You can secure your source with different authentication methods:

# Basic Auth
hookdeck-manager create-source \
  --name "Secured Webhook" \
  --auth-type BASIC_AUTH \
  --auth-username myuser \
  --auth-password mypassword

# HMAC
hookdeck-manager create-source \
  --name "HMAC Secured" \
  --auth-type HMAC \
  --auth-secret mysecretkey

# API Key in Header
hookdeck-manager create-source \
  --name "API Key Secured" \
  --auth-type API_KEY \
  --auth-header-name "X-API-Key" \
  --auth-value "my-api-key"

Listing Sources

# List all sources
hookdeck-manager list-sources

# Get JSON output for programmatic use
hookdeck-manager list-sources --json

Getting Source Details

hookdeck-manager get-source source_id

The output includes:

• Source ID and name
• Source URL (for sending webhooks)
• Authentication configuration
• Creation and update timestamps
• Associated connections

Updating a Source

hookdeck-manager update-source source_id \
  --name "Updated Name" \
  --description "New description"

Deleting a Source

# With confirmation prompt
hookdeck-manager delete-source source_id

# Force delete without confirmation
hookdeck-manager delete-source source_id --force

🎯 Destinations Management

Destinations define where webhook events are forwarded.

Types of Destinations

• HTTP: Standard HTTP endpoint
• CLI: Command line interface
• MOCK_API: Test destination that simulates responses

Creating a Destination

# HTTP Destination
hookdeck-manager create-destination \
  --name "My API" \
  --type HTTP \
  --url "https://myapi.com/webhook" \
  --http-method POST

# CLI Destination
hookdeck-manager create-destination \
  --name "Local Script" \
  --type CLI \
  --path "/path/to/script.sh"

# Mock API for Testing
hookdeck-manager create-destination \
  --name "Mock API" \
  --type MOCK_API

Advanced Configuration

# With Rate Limiting
hookdeck-manager create-destination \
  --name "Rate Limited API" \
  --type HTTP \
  --url "https://api.example.com/webhook" \
  --rate-limit 10 \
  --rate-limit-period minute

# With Authentication
hookdeck-manager create-destination \
  --name "Authenticated API" \
  --type HTTP \
  --url "https://api.example.com/webhook" \
  --auth-type BEARER_TOKEN \
  --auth-token "my-auth-token"

Listing Destinations

# List all destinations
hookdeck-manager list-destinations

# Get JSON output
hookdeck-manager list-destinations --json

Getting Destination Details

hookdeck-manager get-destination destination_id

Updating a Destination

hookdeck-manager update-destination destination_id \
  --name "Updated API" \
  --url "https://new-api.example.com/webhook"

Deleting a Destination

# With confirmation prompt
hookdeck-manager delete-destination destination_id

# Force delete without confirmation
hookdeck-manager delete-destination destination_id --force

🔄 Connections Management

Connections link sources to destinations and define how events flow between them.

Creating a Connection

hookdeck-manager create-connection \
  --name "Payment Processing" \
  --source-id src_123 \
  --destination-id dest_456

Adding Rules to Connections

Rules modify how events are processed:

Retry Rule

hookdeck-manager create-connection \
  --source-id src_123 \
  --destination-id dest_456 \
  --retry-rule \
  --retry-strategy exponential \
  --retry-interval 5 \
  --retry-count 3 \
  --retry-status-codes "500,502,503,504"

Delay Rule

hookdeck-manager create-connection \
  --source-id src_123 \
  --destination-id dest_456 \
  --delay-rule \
  --delay-time 2000

Filter Rule

hookdeck-manager create-connection \
  --source-id src_123 \
  --destination-id dest_456 \
  --filter-rule \
  --filter-conditions '{"headers":{"x-event-type":"payment_succeeded"}}'

Transform Rule

hookdeck-manager create-connection \
  --source-id src_123 \
  --destination-id dest_456 \
  --transform-rule \
  --transform-name "Add Timestamp" \
  --transform-code "module.exports = function(request) { request.body.processed_at = new Date().toISOString(); return request; };"

Managing Connection State

# Pause a connection (events will be held)
hookdeck-manager pause-connection connection_id

# Unpause a connection (held events will be delivered)
hookdeck-manager unpause-connection connection_id

# Disable a connection (won't receive or deliver events)
hookdeck-manager disable-connection connection_id

# Enable a disabled connection
hookdeck-manager enable-connection connection_id

Listing Connections

hookdeck-manager list-connections

Getting Connection Details

hookdeck-manager get-connection connection_id

Updating Connections

# Update basic information
hookdeck-manager update-connection connection_id \
  --name "New Connection Name" \
  --description "Updated description"

# Add rules to existing connection
hookdeck-manager update-connection connection_id --add-rules

# Clear all rules
hookdeck-manager update-connection connection_id --clear-rules

Deleting a Connection

hookdeck-manager delete-connection connection_id

🧙‍♂️ Interactive Connection Creation

The most powerful feature of Hookdeck Manager is the interactive connection creation workflow, which guides you through creating complex connections step by step.

Quick Start

hookdeck-manager connect

or

hookdeck-manager interactive-connection

What It Does

The interactive connection wizard:

• Prompts for a connection name
• Allows selecting an existing source or creating a new one on the fly
• Allows selecting an existing destination or creating a new one on the fly
• Guides you through configuring rules if needed
• Shows a summary before creating the connection
• Creates the connection and provides next steps

Workflow Example

$ hookdeck-manager connect

Interactive Connection Creation
This will guide you through creating a connection between a source and destination.

Enter a name for your connection (optional): Order Processing

Choose a source:
> Use an existing source
  Create a new source

Select a source:
> Shopify Store - SHOPIFY (src_123)
  Payment Webhook - STRIPE (src_456)
  GitHub Events - GITHUB (src_789)

Choose a destination:
> Use an existing destination
  Create a new destination

Select a destination:
> Order API - HTTP (dest_123)
  Inventory Service - HTTP (dest_456)
  Logging Service - HTTP (dest_789)

Do you want to add rules to this connection? (y/N) y

Select rule types to add:
 ◉ Retry - Automatically retry failed requests
 ◯ Delay - Add a delay before processing
 ◉ Filter - Only process requests that match criteria
 ◯ Transform - Modify request data before processing

Select retry strategy:
> Linear - Fixed intervals between retries
  Exponential - Increasing intervals between retries

Enter retry interval (seconds): 5
Enter maximum retry count: 3
Enter status codes to retry (comma-separated): 500,502,503,504

What do you want to filter on?
 ◉ Headers
 ◉ Body
 ◯ Query parameters
 ◯ Path

Enter headers filter condition as JSON: {"x-shopify-topic": "orders/created"}
Enter body filter condition as JSON: {"line_items": {"$exists": true}}

Connection Summary:
Name: Order Processing
Source: Shopify Store (src_123)
Source Type: SHOPIFY
Destination: Order API (dest_123)
Destination Type: HTTP

Rules:
1. retry rule
   Strategy: linear
   Interval: 5 seconds
   Max retries: 3
2. filter rule
   Filter conditions: Set

Do you want to create this connection? (Y/n)

Connection created successfully!
ID: conn_abc123
Name: Order Processing
Source: Shopify Store (src_123)
Destination: Order API (dest_123)
Rules: 2 rules added

Next steps:
• To view this connection: hookdeck-manager get-connection conn_abc123
• To update this connection: hookdeck-manager update-connection conn_abc123
• To pause/disable: hookdeck-manager pause-connection conn_abc123

🛍️ Shopify Webhook Integration

Hookdeck Manager provides a specialized command for setting up Shopify webhooks quickly and easily.

Quick Start

hookdeck-manager shopify

This interactive wizard will guide you through the complete Shopify webhook setup process.

Command Options

# Basic usage with required parameters
hookdeck-manager shopify \
  --name "My Shopify Store" \
  --secret "your_shopify_hmac_secret" \
  --url "https://api.example.com/shopify-webhook"

# With authentication on the destination
hookdeck-manager shopify \
  --name "My Shopify Store" \
  --secret "your_shopify_hmac_secret" \
  --url "https://api.example.com/shopify-webhook" \
  --auth-type BEARER_TOKEN \
  --token "your_api_token"

# Using Basic Auth on destination
hookdeck-manager shopify \
  --name "My Shopify Store" \
  --secret "your_shopify_hmac_secret" \
  --url "https://api.example.com/shopify-webhook" \
  --auth-type BASIC_AUTH \
  --username "user" \
  --password "pass"

# Using API Key in header
hookdeck-manager shopify \
  --name "My Shopify Store" \
  --secret "your_shopify_hmac_secret" \
  --url "https://api.example.com/shopify-webhook" \
  --auth-type API_KEY \
  --header-name "X-API-Key" \
  --header-value "your_api_key"

# Non-interactive mode
hookdeck-manager shopify \
  --name "My Shopify Store" \
  --secret "your_shopify_hmac_secret" \
  --url "https://api.example.com/shopify-webhook" \
  --yes

What It Does

The Shopify command:

• Creates a Shopify-type source with HMAC authentication
• Creates an HTTP destination with the specified URL and authentication
• Creates a connection between them
• Provides next steps for configuring webhooks in your Shopify admin panel

This command greatly simplifies the process of setting up Shopify webhooks by handling all the necessary configuration in one step.

Authentication Options

The Shopify command supports various authentication methods for the destination:

• None: No authentication (default)
• Bearer Token: Standard JWT or OAuth token authentication
• Basic Auth: Username and password authentication
• API Key: API key in header or query parameter
• Custom Header: Custom authorization header

Workflow Example

$ hookdeck-manager shopify

Shopify Webhook Setup Wizard
This will create a Shopify webhook source, destination, and connection.

Enter a name for your Shopify webhook source: My Store

Enter your Shopify HMAC secret: shpss_1234567890abcdef1234567890abcdef

Enter the destination URL to forward webhooks to: https://api.example.com/webhooks/shopify

Select authentication type for the destination:
> None - No authentication
  Bearer Token - JWT or OAuth token
  Basic Auth - Username and password
  API Key - In header or query param
  Custom Header - Custom authorization header

Setup Summary:
Source: My Store (Shopify with HMAC auth)
HMAC Secret: ****cdef
Destination URL: https://api.example.com/webhooks/shopify
Authentication: None

Do you want to proceed with this setup? (Y/n)

Creating Shopify source...
Source created successfully!
ID: src_abc123
Name: My Store
URL: https://webhook.hookdeck.com/source/abc123

Creating destination...
Destination created successfully!
ID: dest_def456
Name: My Store Destination
URL: https://api.example.com/webhooks/shopify

Creating connection...
Connection created successfully!
ID: conn_ghi789
Name: My Store Connection
Source: My Store (src_abc123)
Destination: My Store Destination (dest_def456)

Next Steps:
1. In your Shopify admin panel, go to Settings > Notifications > Webhooks
2. Add a webhook with the URL: https://webhook.hookdeck.com/source/abc123
3. Select the events you want to receive (e.g., order/created, customer/created)
4. Use this secret for verification: shpss_1234567890abcdef1234567890abcdef

Hookdeck CLI Commands:
• To view this connection: hookdeck-manager get-connection conn_ghi789
• To update connection: hookdeck-manager update-connection conn_ghi789
• To add rules: hookdeck-manager update-connection conn_ghi789 --add-rules

🌟 Example Workflows

Complete E-commerce Webhook Setup

# Step 1: Create a source for Shopify webhooks
hookdeck-manager create-source \
  --name "Shopify Orders" \
  --type SHOPIFY \
  --description "Receives order webhooks from Shopify store"

# Step 2: Create destinations for different services
hookdeck-manager create-destination \
  --name "Order Processing API" \
  --type HTTP \
  --url "https://api.mycompany.com/orders" \
  --http-method POST \
  --auth-type BEARER_TOKEN \
  --auth-token "api_token_123"

hookdeck-manager create-destination \
  --name "Inventory Service" \
  --type HTTP \
  --url "https://inventory.mycompany.com/update" \
  --http-method PUT

hookdeck-manager create-destination \
  --name "Customer Analytics" \
  --type HTTP \
  --url "https://analytics.mycompany.com/events" \
  --rate-limit 100 \
  --rate-limit-period minute

# Step 3: Create connections with appropriate rules
hookdeck-manager create-connection \
  --name "Order Processing" \
  --source-id src_shopify \
  --destination-id dest_orders \
  --filter-rule \
  --filter-conditions '{"headers":{"x-shopify-topic":"orders/created"}}' \
  --retry-rule \
  --retry-strategy exponential \
  --retry-count 5

hookdeck-manager create-connection \
  --name "Inventory Updates" \
  --source-id src_shopify \
  --destination-id dest_inventory \
  --filter-rule \
  --filter-conditions '{"headers":{"x-shopify-topic":"orders/created"}}' \
  --transform-rule \
  --transform-name "Extract Line Items" \
  --transform-code "module.exports = function(request) { request.body = { items: request.body.line_items, order_id: request.body.id }; return request; };"

hookdeck-manager create-connection \
  --name "Customer Analytics" \
  --source-id src_shopify \
  --destination-id dest_analytics \
  --filter-rule \
  --filter-conditions '{"headers":{"x-shopify-topic":"customers/created"}}' \
  --delay-rule \
  --delay-time 500

Interactive Workflow

For complex setups, the interactive mode is often easier:

hookdeck-manager connect

Then follow the prompts to create sources, destinations, and connections with rules in a guided workflow.

💡 Tips and Best Practices

Naming Conventions

Use clear, descriptive names for your resources to make management easier:

• Sources: [Service]-[EventType] (e.g., Stripe-Payments, Shopify-Orders)
• Destinations: [Service]-[Purpose] (e.g., API-OrderProcessing, Lambda-Inventory)
• Connections: [Source]-to-[Destination] (e.g., Stripe-to-Accounting)

Security Best Practices

• Use authentication on both sources and destinations when possible
• For sensitive workflows, use HMAC verification on sources
• Regularly rotate authentication credentials
• Use environment variables for API keys rather than command line parameters

Performance Optimization

• Use filters to reduce unnecessary processing
• Apply rate limits to destinations that might get overwhelmed
• Use retry rules with appropriate backoff strategy for resilient connections
• For high-volume sources, create multiple connections with specific filters

Maintenance

• Use descriptive naming for easier troubleshooting
• Document complex transformation code
• Periodically review disabled or paused connections
• Use environment variables in transformation rules for easier updates

❓ Troubleshooting

Common Issues

Authentication Errors

Error: API key is required. Set it via --api-key option or HOOKDECK_API_KEY environment variable.

Solution: Ensure your API key is correctly set either as an environment variable or using the --api-key parameter.

Resource Not Found

Error: Resource not found. Status code: 404

Solution: Double-check that the ID you're using exists and is correct. Use the list commands to verify IDs.

Invalid JSON in Filters or Transformations

Error parsing filter conditions. Must be valid JSON.

Solution: Ensure your JSON is correctly formatted. Use single quotes around the entire JSON string and double quotes within it.

Rate Limiting

Error: Too many requests. Status code: 429

Solution: Reduce the frequency of your API calls or contact Hookdeck support to increase your rate limits.

Getting Help

For more detailed troubleshooting:

• Use the --json flag with get commands to see raw API responses
• Contact Hookdeck support with the command you're trying to run and the complete error message
• Check the Hookdeck documentation for API specifics

🤝 Contributing

Contributions to the Hookdeck Manager CLI are welcome! Whether it's bug reports, feature requests, or code contributions, please feel free to reach out.

Development Setup

git clone https://github.com/yourusername/hookdeck-manager.git
cd hookdeck-manager
npm install
npm run build
npm link

Pull Request Process

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ for the Hookdeck community

Hookdeck Documentation | GitHub Repository

# hookdeck-manager