How to Test and Replay Claude Webhooks Locally

Claude Managed Agent webhooks notify your application when an agent's status changes — when a run starts, when it idles waiting for input, when an outcome evaluation finishes. Testing those events end-to-end during development is awkward without a public HTTPS endpoint, and triggering the same event sequence repeatedly while you debug a handler is even more awkward.

This guide walks you through setting up a local webhook endpoint, wiring it to Claude through Hookdeck, and replaying events on demand using the following steps:

1. Set up a local webhook endpoint
2. Create a Hookdeck connection
3. Configure the webhook endpoint in the Claude Console
4. Test the integration by triggering a Claude agent
5. Replay error or failed events

Relaying your Claude webhooks through Hookdeck makes it easy to consume, monitor, troubleshoot, and replay events while you're building.

Step 1: Set up a local webhook endpoint

You need a server running on your local machine that Claude's webhooks can POST to. For this guide, any HTTP server that listens on a port and logs the request body will do. A minimal Express handler:

mkdir claude-webhook-test && cd claude-webhook-test
npm init -y
npm install express

Create index.js:

cat > index.js << 'EOF'
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/claude', (req, res) => {
  console.log('Received:', JSON.stringify(req.body, null, 2));
  res.sendStatus(200);
});
app.listen(3000, () => console.log('Listening on :3000'));
EOF

Start it:

node index.js

Your handler is now reachable at http://localhost:3000/webhooks/claude — but Claude can't reach localhost. That's where Hookdeck comes in.

Step 2: Create a Hookdeck connection

Hookdeck sits between Claude and your local handler. It gives you a stable public HTTPS URL to register with Claude, queues every incoming event durably, and lets you replay any event with one click.

Create the Hookdeck Connection with the Hookdeck CLI

Install the Hookdeck CLI:

  npm install hookdeck-cli -g
  
  

  yarn global add hookdeck-cli
  
  

    brew install hookdeck/hookdeck/hookdeck
    
    

Authenticate (this opens a browser to log in or create a free Hookdeck account):

hookdeck login

Now run hookdeck listen against your local port and pick a name for the source — claude is fine:

hookdeck listen 3000 claude

The CLI prints a public HTTPS URL that points at your local server. It looks like https://hkdk.events/abc123xyz. Anything Claude POSTs to that URL is forwarded to localhost:3000, queued in Hookdeck, and visible in the Hookdeck dashboard for inspection and replay.

Step 3: Configure the webhook endpoint in the Claude Console

Open the Claude Console, go to Manage > Webhooks, and click Add endpoint.

• URL: paste the Hookdeck public URL from Step 2
• Event types: subscribe to the events you want to test — session.status_run_started, session.status_idled, session.outcome_evaluation_ended, etc.
• Signing secret: Claude generates a whsec_-prefixed secret. Copy it immediately — it's only shown once.

Save the endpoint. Claude is now configured to deliver webhooks to your Hookdeck URL.

Step 4: Test the integration by triggering a Claude agent

Trigger any of the events you subscribed to. The fastest way is to start a Managed Agent session — either from the Console or via the API — and watch events flow through.

In the terminal where you ran hookdeck listen, you'll see each event arrive. In the Hookdeck dashboard you'll see the same events with full request and response details, signature headers, and forwarding status. In your local terminal, your Express handler logs the parsed body.

If your local handler returns a non-2xx response, Hookdeck records the failure and keeps the event in the queue, ready to retry.

Step 5: Replay error or failed events

Where Hookdeck pays for itself during development is replay. Open any event in the Hookdeck dashboard and click Retry to re-deliver it to your local server. You can do this as many times as you want, with whatever code changes you've made in between. No need to trigger another live agent run.

You can also replay any event from the CLI:

hookdeck listen 3000 claude --replay

This is the loop that makes development genuinely productive — trigger once, replay forever, fix bugs without hammering the live API.

Conclusion

Claude Managed Agent webhooks are easy to receive in production but tricky to develop against locally because they require a public HTTPS endpoint, signed payloads, and an at-least-once delivery model that's hard to debug without observability. Hookdeck gives you a stable URL, durable queueing, full request inspection, and one-click replay — all without changing your handler code.

Try Hookdeck for free and start building reliable Claude webhook integrations from day one. For deeper background, see our guide to Claude webhook features and best practices and how to secure and verify Claude webhooks.