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.
# Run directly with npx (no install required)
npx posthook listen
# Or install globally
npm install -g posthookRequirements: Node.js 18.0.0 or higher
Get your API key from your Posthook dashboard.
# 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 listenposthook listenListen for hooks and manually respond to each one:
posthook listenWhen 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
Automatically forward hooks to a local HTTP endpoint:
posthook listen --forward http://localhost:3000The --forward flag takes a base URL — the hook's path is appended automatically. For example, a hook with path /webhooks/order is forwarded to http://localhost:3000/webhooks/order.
Hooks are forwarded as POST requests identical to how Posthook would deliver them in production, including all signature headers (Posthook-Signature, Posthook-Id, Posthook-Timestamp, X-Ph-Signature).
Use --verbose to see full request headers and body:
posthook listen --forward http://localhost:3000 --verboseStore your API key locally for future use.
posthook login
posthook login --api-host http://localhost:8080 # For local developmentClear stored credentials.
posthook logoutListen 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 |
API keys can be provided in three ways (in order of precedence):
- Command line flag:
--api-key <your_key> - Environment variable:
POSTHOOK_API_KEY=<your_key> - Stored credentials: Run
posthook loginonce
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.
Enable debug logging to troubleshoot connection issues:
posthook listen --debug debug.logSensitive fields (data, body, authorization, signature) are automatically redacted in debug logs.
# Basic interactive mode
posthook listen
# Forward to local Express server
posthook listen --forward http://localhost:3000
# Forward with verbose output
posthook listen -f http://localhost:8080 -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- Verify your API key in the Posthook dashboard
- Run
posthook loginto re-authenticate - Check for typos if using
--api-key
- WebSocket delivery must be enabled for your project
- Contact support if you need this feature enabled
- Check that the API host is correct
- Verify your network connection
- If using
--api-host, ensure the server is running
- Verify your local server is running
- Check the URL is correct (including port)
- Use
--verboseto see request details - Check your server logs for incoming requests
| Code | Description |
|---|---|
| 0 | Clean exit (Ctrl+C) |
| 1 | Authentication failure or max reconnect attempts |
- Documentation — guides, concepts, and patterns
- CLI Reference — full command documentation
- Local Development — using the CLI during development
- Quickstart — get started in under 2 minutes
MIT