Hookdeck Channel Plugin for Claude Code
Receive webhooks from any provider (GitHub, Stripe, CI pipelines, monitoring tools) in your Claude Code session via Hookdeck. Hookdeck captures, inspects, and forwards webhook events to Claude with stable URLs, event replay, and filtering — no tunnel setup required.
Channels are in research preview and require Claude Code v2.1.80+.
Use-cases
- Iterate without re-triggering — Capture a webhook once from your provider, then replay it every time you change your channel server code. No need to push another commit or create another test payment.
- Stable webhook URLs across restarts — Your Hookdeck source URL stays the same between sessions. Reconfigure your webhook provider once and it keeps working no matter how many times you restart Claude Code or the CLI.
- Inspect what your channel actually receives — See the full request body, headers, and response for every webhook in the CLI or Hookdeck dashboard. Useful when your channel notification formatting isn't producing what you expect.
- Filter out noise during development — If you're subscribed to all GitHub events but only building a handler for push events, filter at the Hookdeck layer so your channel only receives what you're working on.
- Test multiple event types quickly — Trigger one of each event type from your provider, then selectively replay them from Hookdeck's history as you build handlers for each one.
- Share webhook payloads with teammates — Multiple developers can connect to the same Hookdeck source independently, each forwarding to their own local channel server without stepping on each other.
Architecture
External Service (GitHub, Stripe, CI, etc.)
↓ POST webhook
Hookdeck Event Gateway (cloud)
↓ captures, queues, inspects
Hookdeck CLI (forwards to localhost)
↓
This Plugin (MCP server + HTTP listener)
↓ notifications/claude/channel
Claude Code Session (reacts to events)
Prerequisites
Installation
From a marketplace
/plugin install hookdeck@<marketplace-name>
For development
claude --plugin-dir ./path/to/claude-channel-plugin
Running with channels enabled
Channels must be explicitly enabled per session with --channels:
claude --channels plugin:hookdeck@<marketplace-name>
During the research preview, custom channels aren't on the approved allowlist. To test locally:
claude --dangerously-load-development-channels plugin:hookdeck@<marketplace-name>
Or for a bare MCP server (no plugin wrapper):
claude --dangerously-load-development-channels server:hookdeck-channel
Setup
After installing and enabling the plugin, configure your webhook sources.
Approach A: Manual (simpler)
Run the Hookdeck CLI in another terminal:
hookdeck listen 8788 my-source
Point your webhook provider at the Hookdeck source URL the CLI gives you.
Approach B: Auto-provision (more integrated)
Set HOOKDECK_API_KEY and HOOKDECK_SOURCES environment variables in the plugin's .mcp.json. The plugin auto-creates Hookdeck connections and logs the source URLs on startup. You still need the Hookdeck CLI running to forward events locally:
hookdeck listen 8788 --cli-path /webhook
Configuration
All configuration is via environment variables in the plugin's .mcp.json:
| Variable | Default | Description |
|---|
HOOKDECK_PORT | 8788 | Local HTTP server port |
HOOKDECK_API_KEY | — | Hookdeck API key (enables auto-provisioning) |
HOOKDECK_SOURCES | — | Comma-separated source names to provision |
HOOKDECK_EVENT_FILTER | — | Comma-separated event types to allow (e.g., push,pull_request) |
HOOKDECK_ALLOWED_IPS | — | Comma-separated IPs to allow (empty = allow all; localhost always allowed) |
Testing Locally
With the plugin running, send test webhooks:
./test/test-webhook.sh
Or manually:
curl -X POST http://localhost:8788/webhook \
-H "Content-Type: application/json" \
-H "x-hookdeck-source-name: test-source" \
-H "x-github-event: push" \
-d '{"ref":"refs/heads/main","commits":[{"message":"fix bug"}]}'
Reply Tool
The plugin exposes a hookdeck_reply tool so Claude can send outbound HTTP requests in response to events — post PR comments, acknowledge alerts, trigger downstream services, etc.
How It Works
