Posthook CLI

The official CLI for Posthook.io — a job scheduling API that delivers HTTP callbacks to your application at scheduled times.

This CLI lets you receive scheduled webhook deliveries on your local machine during development, so you can test your webhook handlers without deploying.

Installation

# Run directly with npx (no install required)
npx posthook listen

# Or install globally
npm install -g posthook

Requirements: Node.js 18.0.0 or higher

Quick Start

1. Get Your API Key

Get your API key from your Posthook dashboard.

2. Authenticate

# Interactive login (stores credentials locally)
posthook login

# Or pass API key directly
posthook listen --api-key abc123...

# Or use environment variable
POSTHOOK_API_KEY=abc123... posthook listen

3. Start Listening

posthook listen

Usage

Interactive Mode

Listen for hooks and manually respond to each one:

posthook listen

When a hook arrives, you'll be prompted to:

• Accept (A) - Mark as delivered successfully
• Fail (F) - Reject and trigger retry
• Skip (S) - Let the server timeout and retry

Forward Mode

Automatically forward hooks to a local HTTP endpoint:

posthook listen --forward http://localhost:3000/webhooks

Hooks are forwarded as POST requests identical to how Posthook would deliver them in production, including:

• Content-Type: application/json
• X-Ph-Signature: <hmac-signature>
• Authorization: <if configured>

This lets you test your webhook handlers locally with the exact same request format you'll receive in production.

Use --verbose to see full request headers and body:

posthook listen --forward http://localhost:3000/webhooks --verbose

Commands

posthook login

Store your API key locally for future use.

posthook login
posthook login --api-host http://localhost:8080  # For local development

posthook logout

Clear stored credentials.

posthook logout

posthook listen

Listen for incoming webhook deliveries.

posthook listen [options]

Options:

| Option | Description | |--------|-------------| | -k, --api-key <key> | API key (overrides stored key) | | -f, --forward <url> | Forward hooks to local HTTP endpoint | | -v, --verbose | Show full headers and body (forward mode) | | --api-host <url> | Override API host (local development) | | --debug <file> | Write debug log to file |

Authentication

API keys can be provided in three ways (in order of precedence):

1. Command line flag: --api-key <your_key>
2. Environment variable: POSTHOOK_API_KEY=<your_key>
3. Stored credentials: Run posthook login once

Configuration

Credentials are stored in ~/.posthook/config.json with secure file permissions (0600). The API key is stored unencrypted.

If XDG_CONFIG_HOME is set, config is stored at $XDG_CONFIG_HOME/posthook/config.json instead.

Debugging

Enable debug logging to troubleshoot connection issues:

posthook listen --debug debug.log

Sensitive fields (data, body, authorization, signature) are automatically redacted in debug logs.

Examples

# Basic interactive mode
posthook listen

# Forward to local Express server
posthook listen --forward http://localhost:3000/api/webhooks

# Forward with verbose output
posthook listen -f http://localhost:8080/hooks -v

# Use specific API key without storing it
posthook listen --api-key abc123...

# Local development against dev API
posthook listen --api-host http://localhost:8080

Troubleshooting

"Invalid API key"

• Verify your API key in the Posthook dashboard
• Run posthook login to re-authenticate
• Check for typos if using --api-key

"WebSocket not enabled"

• WebSocket delivery must be enabled for your project
• Contact support if you need this feature enabled

"Connection refused"

• Check that the API host is correct
• Verify your network connection
• If using --api-host, ensure the server is running

Forward mode not receiving hooks

• Verify your local server is running
• Check the URL is correct (including port)
• Use --verbose to see request details
• Check your server logs for incoming requests

Exit Codes

| Code | Description | |------|-------------| | 0 | Clean exit (Ctrl+C) | | 1 | Authentication failure or max reconnect attempts |

License

MIT