Documentation Menu

CLI Diagnostics & Forensics

Debug webhook failures without ever leaving your terminal.

Context switching ruins developer productivity. When a webhook fails on your local machine, you shouldn't have to open a web browser, dig through logs, and manually decode payloads.

The Hookmetry CLI brings our entire forensic intelligence engine directly to your terminal. Authenticate once, and you can diagnose and remediate errors instantly.

1. The Forensic Timeline: hookmetry diagnose

When a webhook signature fails, copy the log ID from your server logs and run diagnose. Hookmetry will generate a deterministic reconstruction timeline showing exactly which cryptographic step failed.

hookmetry diagnose wl_abc123def456
🔬 Hookmetry AI — Diagnostic Report
Fetching reconstruction timeline for log: wl_abc123def456...
[1] ✔ Extract Signature Header
[2] ✔ Parse Stripe Signature Format (t=...,v1=...)
[3] ✔ Validate Timestamp
[4] ✘ HMAC-SHA256 Match — Signature does not match. Body was likely parsed JSON instead of raw bytes.
🎯 Root Cause Identified: stripe/parsed_body_mismatch

2. Automated Remediation: hookmetry explain

Once you've diagnosed the failure, use the explain command to invoke Hookmetry AI. It will analyze the forensic mismatch and output the exact copy-paste code fix for your framework.

hookmetry explain wl_abc123def456
🤖 Hookmetry AI — Intelligent Analysis
The signature mismatch occurred because Express.js parsed the request body as JSON before Stripe's signature validation could access the raw bytes.
📋 Code Fix (Node.js):
// Use express.raw() for Stripe webhook routes, NOT express.json()
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_SECRET);
});

Pro-Tip: Ultra-Fast Caching

AI generations are cached based on the structural fingerprint of the failure. If you or your team run into the same error twice, the CLI will return the fix instantly (in ~50ms) without burning your AI limits.

Was this page helpful?

Your feedback helps us improve the docs.