DEV Community: Ahmed Rehan

Agent assets need a lifecycle, not a dumping ground

Ahmed Rehan — Mon, 18 May 2026 09:08:08 +0000

I recently shipped agent-harness v1.0.0.

It is a Node.js / TypeScript CLI for discovering, staging, activating, and wiring reusable AI-agent assets across VS Code / GitHub Copilot, Cursor, OpenCode, Zed, Claude Code, and Pi.

The first announcement explained what it is.

This follow-up is about the design problem behind it — and why I am looking for more than page views or stars.

I want criticism, feature suggestions, issue reports, tickets, and code contributions from people who actually use AI coding tools in real projects.

The problem is not “more context”

A lot of AI coding workflows drift toward the same pattern:

collect more prompts
collect more skills
collect more examples
collect more MCP configs
collect more instructions
put them somewhere the model can see

That can be useful, but it has a cost.

Context is not free. Even when the tokens are technically available, attention is still scarce. Irrelevant instructions compete with useful ones. Tool-specific assumptions leak into repos where they do not belong. Old experiments stick around because removing them is less obvious than adding another file.

At some point the workflow stops feeling like “better assistance” and starts feeling like a context landfill.

The question I wanted to explore was:

How do you make useful agent assets portable across projects and tools without dragging everything into every workspace?

That question became agent-harness.

Why a lifecycle?

The core idea in agent-harness is that reusable agent assets should move through a lifecycle:

discover
mirror / stage
install
activate
wire

That may sound like extra ceremony. In some cases, it probably is.

But the lifecycle exists because “available somewhere” and “active in this repo right now” are very different states.

A skill, instruction, prompt pack, MCP server, or workflow might be useful in general but wrong for a specific repo. It might be relevant to a frontend project but noise in a backend service. It might be useful for Cursor but not for Claude Code. It might be safe to stage but not safe to activate automatically.

A lifecycle gives the system places to make those distinctions.

Discovery should not mean activation

One of the mistakes I wanted to avoid was treating discovery as permission to inject context.

Discovery should answer:

What might be relevant?

Activation should answer:

What should actually be active here?

Those are not the same question.

If a project looks like a Flutter app, it may be reasonable to discover mobile, Android, Firebase, testing, and UI-related assets. But that does not mean every vaguely mobile-related asset should be wired into the editor context.

The tighter the activation boundary, the less likely the system is to bloat the workspace with clever-but-irrelevant material.

Host-aware wiring matters

Different AI coding hosts expose different surfaces.

VS Code / GitHub Copilot, Cursor, OpenCode, Zed, Claude Code, and Pi do not all consume project instructions, prompts, tools, and local assets in the same way.

Pretending they are the same usually produces either:

a lowest-common-denominator setup that wastes host-specific strengths, or
a messy pile of adapters hidden behind vague “it works everywhere” claims

agent-harness leans into host differences instead. It tries to keep assets reusable while still wiring them through the surfaces each host actually supports.

That is the bet, at least.

It may turn out that the abstraction is too complex. That is exactly the kind of feedback I want.

The uncomfortable part: this started vibe-coded

This project was mostly vibe-coded at the start.

I think that matters to say plainly.

The good part is that it came from real workflow pain and moved quickly. The bad part is that vibe-coded systems can easily grow accidental abstractions that make sense only to the person building them.

So after the initial build, I pushed it through a stricter phase:

release audits
real workspace testing
Windows validation
issue-driven cleanup
host adapter tightening
docs and changelog cleanup
release workflow hardening

The result is more disciplined than the prototype, but I still do not want to assume the idea is automatically good.

What I want from other developers

I am not looking for generic praise on this one.

I am looking for validation or invalidation.

Useful feedback would be things like:

“this should be much smaller”
“this host should not be supported”
“this lifecycle is unnecessary ceremony”
“this should just be config files”
“this breaks in my repo because…”
“the restrained alternative framing does / does not hold up”

I would also really value concrete contribution paths:

feature suggestions for missing lifecycle steps or host surfaces
issues/tickets for rough edges, unclear docs, or broken assumptions
PRs that improve host adapters, discovery sources, tests, docs, or examples
small reproducible fixtures from real projects where the selection logic gets it wrong
examples of workflows this should support but currently does not

If you try it, the most useful thing you can do is open an issue or discussion with:

repo type / stack
host used
OS
what you expected
what actually happened
what felt confusing or unnecessary
whether the core idea seems useful or wrong
what feature or simplification you would want next

Links:

Repo: https://github.com/ar27111994/agent-harness
Release: https://github.com/ar27111994/agent-harness/releases/tag/v1.0.0
npm: https://www.npmjs.com/package/@ar27111994/agent-harness
Feedback discussion: https://github.com/ar27111994/agent-harness/discussions/218

If the idea is wrong, I would rather learn that early.

If the idea is useful but incomplete, I would love help shaping it through issues, feature requests, and PRs.

I built a more restrained alternative to giant AI skill bundles

Ahmed Rehan — Fri, 08 May 2026 13:42:35 +0000

I just shipped agent-harness v1.0.0.

It’s a Node.js / TypeScript CLI for discovering, staging, activating, and wiring reusable AI-agent assets across:

VS Code / GitHub Copilot
Cursor
OpenCode
Zed
Claude Code
Pi

Links:

Repo: https://github.com/ar27111994/agent-harness
Release: https://github.com/ar27111994/agent-harness/releases/tag/v1.0.0
npm: https://www.npmjs.com/package/@ar27111994/agent-harness
Feedback discussion: https://github.com/ar27111994/agent-harness/discussions/126

Why I made this

This project came from a very specific frustration.

There are already a lot of big all-in-one AI skills/prompts/context bundles out there:

antigravity-awesome-skills
cursor-skills
awesome-agent-skills
awesome-claude-skills
awesome-copilot
and similar projects in that orbit

A lot of those are useful. I’m not against them.

But for my own day-to-day project mix, they often felt too blunt.

The problem wasn’t “I need more context.”

It was more like:

too much irrelevant context getting pulled in
too little selectivity
too much bundle gravity
not enough control over what gets wired where
too much risk of bloating already-expensive context windows

So I wanted something narrower and more restrained.

Not a mega-bundle.
Not a giant dump of everything.
Not “install this, and now your AI stack has 500 things attached to it.”

I wanted something that tries to answer a more practical question:

How do you make reusable agent assets portable across tools and projects without turning every repo into a context landfill?

That’s the reason agent-harness exists.

What it actually does

At a high level, agent-harness manages a lifecycle for reusable agent assets:

discover what might be relevant to a workspace
mirror and stage reproducible artifacts
install them into lifecycle-aware host stores
activate selected assets into runtime views
wire them into the target host/workspace

The important part for me is not just that it does these steps.

It’s that it tries to do them selectively and host-aware, instead of treating every tool as one undifferentiated pile of prompts and skills.

That distinction mattered a lot in practice.

What I was optimizing for

I was not trying to build the biggest possible agent asset bundle.

I was optimizing for:

portability across different hosts
reuse across different kinds of repos
more disciplined context injection
less irrelevant baggage
a workflow that survives real product development instead of just looking impressive in a screenshot

That’s also why the project ended up focusing on discovery, staging, activation, and wiring instead of just curating one huge collection.

Honest note: this was mostly vibe-coded

This project was mostly vibe-coded at the start.

That probably shows in both good and bad ways.

The good side is that it moved quickly and came from a very real pain point.
The bad side is that projects built like this can drift into strange abstractions, workflow-specific assumptions, and over-engineering.

So after getting the core idea working, I pushed it through a much less romantic phase:

release audits
real workspace testing
Windows-specific validation
issue-driven cleanup
host adapter tightening
docs/changelog/release workflow cleanup

In other words: it started loose, then got forced into a stricter shape.

What I want now is criticism

At this point, I’m not really looking for generic applause.

What I want most is feedback — especially negative feedback.

Questions I actually want answered:

Is this solving a real problem, or mostly my problem?
Is the “restrained alternative” framing actually valid?
Which parts feel over-engineered?
Which hosts are worth supporting, and which are not?
Where does the abstraction break down?
What should be removed or simplified?
Where would this fail in your real workflow?

If you try it and it feels wrong, that is useful.
If you think the whole premise is flawed, that is useful too.
If you think this should be much smaller, much dumber, or much more opinionated, that’s useful.

Please open issues if you test it

The best outcome from posting this is not traffic.
It’s not stars.
It’s not generic “nice work.”

The best outcome is:

issue reports
criticism
real-world friction reports
product validation or invalidation

If you try it, please open an issue or drop feedback in the GitHub discussion.

Feedback discussion: https://github.com/ar27111994/agent-harness/discussions/126

If possible, include:

repo type/stack
host used
OS
what you expected
what actually happened
what felt confusing, unnecessary, or weak
whether the core idea itself seems useful or not

If your reaction is “this is overbuilt” or “this is the wrong abstraction,” please tell me.

That’s honestly the kind of signal I’m looking for right now.

[Boost]

Ahmed Rehan — Thu, 22 Jan 2026 16:21:28 +0000

Ahmed Rehan

Jan 21

Fixing Google Antigravity Pro Authentication on Windows 10 + WSL2

#programming #vibecoding #linux #antigravity

Comments

6 min read

Fixing Google Antigravity Pro Authentication on Windows 10 + WSL2

Ahmed Rehan — Wed, 21 Jan 2026 17:33:30 +0000

Google Antigravity is Google's new agent-first IDE that promises powerful AI-assisted development. However, getting the Pro features to work on Windows 10 with WSL2 (Ubuntu 24.04.3 LTS) can be challenging due to authentication issues. This comprehensive guide will walk you through every step needed to get your Pro/Ultra subscription working seamlessly.

The Problem

When running Antigravity in WSL2, the authentication handshake between your Linux terminal and Windows browser often breaks or times out. This happens because WSL2 is a virtualized environment, and the redirect token struggles to find its way back to the WSL instance.

Common symptoms include:

Browser opens but IDE stays on loading screen
Browser Authentication is successful but the Agent Panel still says "Reqire Authentication" (or something similar), even though the Antigravity Settings > Account Screen shows Account as already signed in.
"Invalid Token" or "Login Expired" errors
"Not Eligible" or "Unauthorized" messages
Empty responses when running agy commands

Prerequisites

Before starting, ensure you have:

Windows 10 with WSL2 installed
Ubuntu 24.04.3 LTS (or similar)
Google Antigravity installed on Windows
A Google AI Pro or Ultra subscription using a personal Gmail account.

Step 1: Fix the Silent Login Loop

The first issue to address is WSL2's default NAT networking, which can hide the local ports Antigravity uses to listen for login signals.

Enable Mirrored Networking

On Windows, navigate to %USERPROFILE% (e.g., C:\Users\YourName)
Create or edit a file named .wslconfig
Add the following configuration:

[wsl2]
networkingMode=mirrored

Restart WSL by opening PowerShell as Administrator and running:

wsl --shutdown

Note: You may start getting this message on WSL Startup, especially on Windows 10 (shouldn't theoretically appear on Windows 11):

wsl: Mirrored networking mode is not supported: Windows version 19045.6466 does not have the required features.
Falling back to NAT networking.

In which case, you should remove the unsupported setting from your global config to get rid of the warning every time you boot/reboot and open Ubuntu, as WSL2 cannot enable this mode and defaults back to the standard NAT (Network Address Translation).

Instead, you can try the following config to ensure that Agents always reliably reach local addresses (Supported on Windows 10):

[wsl2]
localhostForwarding=true

Add or ensure these lines exist in %USERPROFILE%\.wslconfig. Save and run wsl --shutdown in your terminal.

Step 2: Synchronize Your System Clock

Google's OAuth 2.0 authentication is highly sensitive to time drift. WSL2 clocks often drift when a laptop sleeps (like in my case), causing tokens to be rejected as expired.

Run this in your Ubuntu terminal:

sudo ntpdate time.windows.com

# If you don't have ntpdate installed:
sudo apt install util-linux-extra && sudo hwclock -s

Step 3: Try Authentication again

If GUI login continues to fail, manually Sign out from your account in the Antigravity Settings > Account Screen.
Close and Restart the IDE.
Click on the Google Sign in button in the top right and Authorize your Google AI Pro account.
Close the Antigravity Sign-in confirmation page.
If the issue persists, repeat the first step and continue reading below.

Step 4: Verify Account Eligibility

Many authentication failures are actually due to account restrictions:

Account Type

Personal accounts (@gmail.com) have the highest success rate
Workspace accounts may require admin approval for "Experimental Google AI Services"

Regional Matching

Ensure your Windows Region, Google Account Region, and IP address (no VPN) all match. Mismatched regions can cause silent authentication failures.

Step 5: Fix Missing WSL Extension Scripts

A known bug in early Antigravity builds causes missing WSL helper scripts. Here's how to fix it:

Manual Script Extraction

Download the Remote - WSL extension from the VS Code Marketplace
Click "Download VSIX" (downloads a .vsix file) if in IDE extensions panel or use a tool like VSIX Downloader for web download.
Rename the file from .vsix to .zip
Open the zip and navigate to extension/scripts/
Copy all files (especially wslCode.sh and wslDownload.sh)
Paste into: %LOCALAPPDATA%\Programs\Antigravity\resources\app\extensions\antigravity-remote-wsl\scripts\

Fix the Launcher ID

Even with scripts present, you need to update the extension ID reference:

Navigate to %LOCALAPPDATA%\Programs\Antigravity\bin\
Open the antigravity file in Notepad
Find: WSL_EXT_ID="ms-vscode-remote.remote-wsl"
Change to: WSL_EXT_ID="google.antigravity-remote-wsl"
Save and restart your WSL terminal

Test WSL Sign In (Command Palette Method)

Try Authentication in WSL:

Open Antigravity on Windows
Press Ctrl + Shift + P
Type "WSL" and select Remote-WSL: Connect to WSL
The bottom-left corner should show [WSL: Ubuntu]
Try signing in from this connected state

Step 6: Create the WSL-to-Windows Bridge

To use agy commands from your Ubuntu terminal, you need to create a proper bridge to the Windows binary.

Create the Wrapper Script

Create the local bin directory:

mkdir -p ~/.local/bin

Create the agy wrapper (replace [YOUR_WINDOWS_USERNAME] with your actual Windows username):

cat > ~/.local/bin/agy <<'EOF'
#!/usr/bin/env bash
# Robust wrapper to bridge WSL -> Windows CMD -> Antigravity
# REPLACE [YOUR_WINDOWS_USERNAME] with your actual folder name

WIN_USER="[YOUR_WINDOWS_USERNAME]"
WIN_PATH="C:\\Users\\${WIN_USER}\\AppData\\Local\\Programs\\Antigravity\\bin\\antigravity.cmd"

# Call via cmd.exe to ensure Windows environment is initialized
# cd to C: drive to avoid UNC path warnings
cd /mnt/c && cmd.exe /c "${WIN_PATH}" "$@"
EOF

Make it executable:

chmod +x ~/.local/bin/agy

Add to your PATH:

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify Your Windows Username

Before running the wrapper, verify your path:

ls /mnt/c/Users/

Update the WIN_USER variable in the script to match exactly how your Windows username folder is spelled.

Enable WSL Interoperability

Ensure WSL can launch Windows processes by checking /etc/wsl.conf:

cat /etc/wsl.conf

If it doesn't exist or is empty, create it with these settings:

[interop]
enabled=true
appendWindowsPath=true

Then restart WSL with wsl --shutdown from PowerShell.

Step 7: Verify Pro Authentication

Once everything is set up, verify your CLI Setup:

# Check version
agy --version

# List available commands
agy --help

# Open IDE in current directory
agy .

Now try signing in again to your Google account. The Agent Panel should be available now, and the Antigravity Settings > Account Screen shows Account as already signed in. Expected output for Agent Panel:

Tier: Pro or Ultra
Model: Gemini 3 Pro or Gemini 3 Flash, etc.
Token Limit: 1M+ tokens

Use Pro Agents

Now you can invoke high-level agents directly on your WSL files:

agy chat "Analyze the structure of this repo and suggest refactoring opportunities"

Because you're authenticated as Pro, the agent will use the full index to understand your entire codebase structure.

Troubleshooting Quick Reference

Issue	Symptom	Fix
Network	Browser opens, IDE stays loading	Enable `networkingMode=mirrored` in `.wslconfig`
Clock Drift	"Invalid Token" or "Login Expired"	Run `sudo hwclock -s`
Account Type	"Not Eligible"	Use personal `@gmail.com` account
Missing Scripts	IDE won't connect to WSL	Download and extract scripts from VS Code Marketplace
Wrong Extension ID	Connection fails silently	Update `WSL_EXT_ID` in launcher script
UNC Path Warnings	Warnings in terminal output	Use `cd /mnt/c &&` in wrapper script

Common Commands

# Open current directory in Antigravity
agy .

# Check process usage and diagnostic information
agy --status

# Check version
agy --version

# Get help
agy --help

Pro Tips

Persistent Sessions: Enable "Persistent Agent" in Antigravity UI to keep agents running even if you close the terminal
Project Indexing: Let Antigravity fully index your project before asking complex questions for better results
Token Limits: Pro users get 1M+ token context windows, perfect for analyzing large codebases
Regional Consistency: Avoid using VPNs during authentication to prevent region mismatch issues

Conclusion

Getting Google Antigravity Pro working on WSL2 requires bridging the gap between the Windows and Linux environments. By following these steps—fixing networking, synchronizing clocks, creating proper symlinks, and enabling interoperability—you'll unlock the full power of Google's agentic IDE.

The effort is worth it: once configured, you'll have access to powerful AI agents that can understand and refactor your entire codebase, all while working seamlessly in your WSL2 development environment.

Additional Resources

Last updated: January 2026 | Tested on Windows 10 + WSL2 Ubuntu 24.04.3 LTS

Stop paying for webhook debuggers. I built a better one (Open Source).

Ahmed Rehan — Thu, 15 Jan 2026 13:40:27 +0000

The Struggle

I remember the payment bug that kept me up until 3 AM.
Stripe was sending a invoice.payment_failed webhook, but only in production.
I checked my logs: Truncated.
I checked my tunneling tool: Session expired.
I checked my SaaS bin: History limit reached.

I realized I didn't have a debugging tool; I had a toy.

The Solution: Webhook Debugger

I decided to build my own solution. But I didn't just want a "bucket" that catches requests. I wanted to build a Reference Implementation for how a modern, secure Node.js application should look in 2026.

Here are the 13 Engineering Patterns I used to build it:

1. Global SSE Heartbeat & Padding 💓

Most SSE implementations leak memory by creating a timer per connection.
My Approach: A single setInterval iterates a Set of clients.
The Pro Tip: I added res.write(' '.repeat(2048)) (2KB whitespace) and X-Accel-Buffering: no headers. Why? Because corporate firewalls (and Nginx) love buffering streams. The padding forces them to flush the connection immediately.

2. SSRF Protection (DNS & IP Verification) 🛡️

Allowing user-defined webhooks is dangerous (Server-Side Request Forgery).
The Fix: I wrote a custom validator in src/utils/ssrf.js that resolves the DNS before the request. It checks the IP against a blocklist of private ranges (RFC 1918) and cloud metadata services (169.254.169.254). It even handles IPv4-mapped IPv6 addresses (::ffff:127.0.0.1).

3. Deep Replay with Exponential Backoff 🔄

Retrying a failed webhook isn't just "try again".
The Logic: If the destination yields a transient error (ECONNABORTED, 503), the system waits 1s, then 2s, then 4s.
Header Stripping: The replay engine automatically strips sensitive headers (Authorization, Cookie) so you don't accidentally send production credentials to your local dev environment.

4. Timing-Safe Authentication ⏱️

Never compare API keys with ===.
The Attack: An attacker can measure how long your server takes to say "No" to guess the key character-by-character.
The Fix: I use crypto.timingSafeEqual in src/utils/auth.js to ensure the comparison takes the exact same time whether the key is 99% correct or 0% correct.

5. Memory-Safe Rate Limiting (LRU) 🧠

Standard rate limiters are often purely in-memory maps. If a botnet hits you with 1 million IPs, your server crashes (OOM).
The Pattern: My RateLimiter uses a Sliding Window with LRU Eviction. It hard-caps at 1,000 entries. If the map is full, the oldest IP is evicted to make room. It prioritizes stability over strictness.

6. Memory-Safe Dataset Filtering 🔍

Searching for a single timestamp in a 1GB JSON dataset will crash a standard Node.js process.
The Solution: Iterative Pagination. The /replay endpoint reads chunks of 1000 items (dataset.getData({ limit, offset })), searches for the event ID, and fetches the next chunk only if not found. This ensures we never load the entire dataset into memory.

7. Input Sanitization & Coercion 🧹

Inputs from the wild are messy. Strings look like numbers; booleans look like strings.
The Pattern: A dedicated coerceRuntimeOptions utility in src/utils/config.js recursively walks the input object, coercing "true" -> true and "5" -> 5, ensuring the runtime configuration isn't crashed by type mismatches.

8. Index.html Caching 🚀

We serve a UI, but we aren't a CDN.
The Optimization: The index.html template is read from disk once at startup and cached in a string variable (indexTemplate). Placeholders like {{VERSION}} are replaced on-the-fly using escapeHtml(), but the disk I/O cost is paid only once.

9. Bootstrap Validation Logic 🩹

What happens if the user manually edits the INPUT.json and breaks the JSON syntax?
Self-Healing: The ensureLocalInputExists function in src/utils/bootstrap.js detects corrupt JSON on startup. Instead of crashing, it automatically renames the bad file to .tmp and writes a fresh default configuration, logging a warning. The app always starts.

10. Optimized Headers ⚡

Every millisecond counts.

Content-Encoding: identity: Disables gzip for the SSE stream (gzip buffers, which kills real-time).
Cache-Control: no-cache: Forces browsers to verify the stream status.
Connection: keep-alive: Critical for long-lived streams.

11. Testing Asynchronous Code 🧪

Testing streaming and retries is notoriously hard.
The Strategy: We use jest with custom helpers (waitForCondition in tests/helpers/test-utils.js) and mocked timers. In resilience.test.js, we mock axios to fail exactly twice with ECONNABORTED to verify the retry logic attempts exactly 3 times before giving up.

12. Hot-Reloading (Zero Downtime Config) 🔥

The Problem: Restarting the server just to change the API key or add a webhook URL loses all SSE connections.
The Solution: A background poller in src/main.js reads the INPUT.json from the Key-Value Store every 5 seconds. When a change is detected:

It diffs the new config against the old one.
It updates middleware (body parser limits, rate limiter), auth keys, and webhook counts dynamically.
It reconciles the webhook IDs: if the user increased urlCount, new IDs are generated; if decreased, no IDs are removed to prevent data loss.

This is all enabled by the loggerMiddleware.updateOptions() function, which allows runtime reconfiguration of the logger instance.

13. Escape the "SaaS Tax" (Self-Hosting) 💸

If you are an agency handling 50 clients, paying $30/mo per seat for debugging tools adds up.
Since this is a standard Dockerized Node.js app, you can deploy it to your own generic VPS.

FROM apify/actor-node:20
COPY . .
RUN npm install
CMD npm start

GitHub Repo (v2.8.7 is out now!)

How to Debug Webhook Integrations in Minutes (Step-by-Step Guide)

Ahmed Rehan — Thu, 25 Dec 2025 15:15:33 +0000

Debugging webhooks is painful. You can't see what's being sent, signature verification fails mysteriously, and testing edge cases requires complex setups.

In this tutorial, I'll show you how to debug webhook integrations in minutes using Webhook Debugger & Logger.

What You'll Accomplish

By the end of this tutorial, you'll:

✅ Capture webhook requests from any service (Stripe, Shopify, etc.)
✅ Use "Launch Packs" for instant, pre-configured setup
✅ Inspect headers, body, and metadata in real-time
✅ Verify signatures with Raw Request Data
✅ Replay requests to test idempotency
✅ Secure your logs with CIDR/Bearer Auth

⏱️ Time required: ~10 minutes

Prerequisites

Free Apify account (sign up with email or GitHub)
A service that sends webhooks (Stripe, GitHub, Shopify, etc.)
No coding required for basic usage

What You'll Achieve

By the end, you'll have a complete webhook debugging workflow that:

Captures every incoming request
Shows raw data for signature debugging
Allows you to replay requests for testing
Exports logs as JSON/CSV

Real example: I debugged a Stripe payment webhook in 8 minutes using this approach. Previously took me 3+ hours.

Step 1: Access Webhook Debugger & Logger

Go to the Webhook Debugger page on Apify Store.

If you don't have an Apify account:

Click "Try for free"
Sign up with email or GitHub (takes 30 seconds)
You'll be redirected to Apify Console

What to expect: You'll see the Actor's input configuration page.

Step 2: Configure Basic Settings

You'll see the input form with these key fields:

URL Count (required)

How many webhook URLs to generate (1-10)

{
  "urlCount": 3
}

Example: If you're testing Stripe payments, GitHub webhooks, and Shopify orders, set this to 3.

Launch Pack Settings (v2.7.0 Optimized)

Choose a pre-configured scenario for your stack:

Shopify Launch Pack: 72h retention + sub-10ms logic.
Stripe Hardening Pack: RAW body capture for signature validation.
Slack Block Kit: Interaction mocking and payload validation.

Basic configuration example:

{
  "urlCount": 3,
  "retentionHours": 24
}

Step 3: Advanced Configuration (Optional)

For more control, expand the advanced settings:

Max Payload Size

Maximum request body size (default: 10MB)

{
  "maxPayloadSize": 10485760
}

Enable JSON Parsing

Automatically parse JSON payloads (default: true)

{
  "enableJSONParsing": true
}

JSON Schema Validation (v2.0+)

Reject invalid payloads automatically:

{
  "jsonSchema": {
    "type": "object",
    "required": ["event", "amount"],
    "properties": {
      "event": { "type": "string" },
      "amount": { "type": "number" }
    }
  }
}

When to use: Testing API integrations that must conform to a specific payload structure.

Step 4: Run the Actor

Click the "Start" button
Status changes to "Running"
Typically takes 5-10 seconds to spin up

⚠️ Tip: You can close the page - the Actor continues running in the background.

What's happening: The Actor is starting a serverless container and generating your webhook URLs.

Step 5: Get Your Webhook URLs

Once running, there are two ways to get your URLs:

Method 1: Live View

Click "Live View" tab to see the web interface with your URLs.

Method 2: Key-Value Store

Go to Storage → Key-value stores
Look for "WEBHOOK_STATE" key
You'll see your webhook IDs

URL Format

https://<actor-run-id>.runs.apify.net/webhook/<webhook-id>

Example:

https://abc123xyz.runs.apify.net/webhook/wh_abc123
https://abc123xyz.runs.apify.net/webhook/wh_def456
https://abc123xyz.runs.apify.net/webhook/wh_ghi789

💡 Pro tip: Bookmark these URLs for the duration of your testing.

Step 6: Configure Your Service

Now configure your webhook source (Stripe, GitHub, etc.) to send to your URL.

Example: Stripe

Go to Stripe Dashboard → Developers → Webhooks
Click "Add endpoint"
Paste your webhook URL: https://<run-id>.runs.apify.net/webhook/wh_abc123
Select events (e.g., payment_intent.succeeded)
Save

Example: GitHub

Go to Repository → Settings → Webhooks
Click "Add webhook"
Paste your URL
Select events (e.g., push, pull_request)
Save

What happens next: Any webhook sent to this URL will be captured and logged.

Step 7: Trigger a Test Webhook

There are two ways to test:

Method 1: Service Test Button

Most services have a "Send test webhook" button. Use it!

Method 2: Manual cURL

curl -X POST https://<run-id>.runs.apify.net/webhook/wh_abc123 \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.success", "userId": "user_123", "amount": 9999}'

What you'll see: Request appears in the Dataset within 1-2 seconds.

Step 8: View Results in Real-Time

Option 1: Dataset Tab

Go to Storage → Dataset
See all captured requests
Click any item to see full details

Option 2: Real-time Streaming (Advanced)

Use Server-Sent Events (SSE) for live monitoring:

curl -N https://<run-id>.runs.apify.net/log-stream

What You'll See

Each captured request includes:

{
  "timestamp": "2025-12-25T14:31:45Z",
  "webhookId": "wh_abc123",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "user-agent": "Stripe/1.0",
    "stripe-signature": "t=1735137105,v1=abc123..."
  },
  "body": "{\"type\": \"payment.success\", \"amount\": 9999}",
  "queryParams": {},
  "size": 78,
  "contentType": "application/json",
  "processingTime": 12,
  "remoteIp": "54.187.174.169",
  "statusCode": 200
}

Step 9: Debug Signature Verification

This is where raw data access becomes crucial.

The Problem

Signature verification fails because you're comparing the signature against the PARSED JSON, not the raw bytes.

The Solution

Use the captured raw body:

const crypto = require("crypto");

// From Webhook Debugger logs:
const rawBody = '{"type": "payment.success", "amount": 9999}';
const signature = "t=1735137105,v1=abc123..."; // from stripe-signature header
const secret = "whsec_yourStripeSecret";

// Extract timestamp and signature
const [t, v1] = signature.split(",").map((s) => s.split("=")[1]);

// Compute expected signature
const payload = `${t}.${rawBody}`;
const hmac = crypto.createHmac("sha256", secret);
hmac.update(payload, "utf8");
const expectedSignature = hmac.digest("hex");

// Verify
const isValid = crypto.timingSafeEqual(
  Buffer.from(v1),
  Buffer.from(expectedSignature)
);

console.log("Signature valid:", isValid);

💡 Key insight: You MUST use the raw body from the logs, not your parsed JSON object.

Step 10: Test Idempotency with Replay

Use the /replay API to test duplicate event handling:

curl -X POST https://<run-id>.runs.apify.net/replay/wh_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://myapp.com/webhook",
    "headers": {
      "X-Test-Replay": "true"
    }
  }'

This resends the captured webhook to your destination, allowing you to verify that your app handles duplicates correctly.

Step 11: Export and Analyze

Export your logs for further analysis:

Via Console:

Go to Storage → Dataset
Click "Export"
Choose format (JSON, CSV, Excel)
Download

Via API:

curl "https://api.apify.com/v2/datasets/<dataset-id>/items?format=json&clean=1" \
  -H "Authorization: Bearer <your-api-token>"

Use cases for exported data:

Share with team members
Import into analytics tools
Create custom reports
Archive for compliance

Pro Tips for Better Results

1. Use Specific Webhook IDs

Create different IDs for different services:

wh_stripe for Stripe
wh_github for GitHub
wh_shopify for Shopify

2. Filter Logs

Use query parameters to filter:

/logs?webhookId=wh_stripe&method=POST&statusCode=200

3. Force Status Codes

Test error handling:

https://<run-id>.runs.apify.net/webhook/wh_abc123?__status=500

4. Simulate Latency (v2.0+)

Test timeout handling:

{
  "customResponseDelay": 5000 // 5 second delay
}

Troubleshooting

Issue: "Webhook not found or expired"

Solution: Check that:

The webhook ID is correct
The Actor is still running
The retention period hasn't expired

Use /info endpoint to verify:

curl https://<run-id>.runs.apify.net/info

Issue: Requests not appearing

Solution:

Verify the URL is correct
Check that the Actor is in "Running" state
Ensure the service is actually sending webhooks

Issue: JSON parsing errors

Solution: Check the enableJSONParsing setting and verify the payload is valid JSON.

Conclusion

You now have a complete webhook debugging workflow! 🎉

What you learned:
✅ How to capture webhooks without localhost tunneling
✅ How to inspect raw request data for signature debugging
✅ How to replay webhooks to test idempotency
✅ How to export and analyze webhook logs

Time saved: What used to take 3-4 hours now takes 10-15 minutes.

Try Webhook Debugger yourself: https://apify.com/ar27111994/webhook-debugger-logger

Questions? Drop them in the comments! 👇

👍 If this tutorial helped you, please give it a like and follow for more webhook debugging tips!

The 6 Best Webhook Testing Tools for Developers in 2025

Ahmed Rehan — Thu, 25 Dec 2025 15:09:49 +0000

Webhooks power modern web apps, but when they fail, debugging becomes a nightmare. After testing dozens of tools while building integrations for Stripe, GitHub, and Shopify, here are the 6 best webhook testing tools for developers in 2025.

TL;DR

🥇 Best overall: Webhook Debugger & Logger (pay-per-event, great features)
🏠 Best for localhost: ngrok (tunneling classic)
🎯 Best for quick tests: Webhook.site (free, simple)
🏢 Best for enterprise: Hookdeck (production-grade, expensive)
💰 Best free option: RequestBin (basic but gets the job done)
🎭 Best for mocking: Beeceptor (custom API responses)

What I Looked For

Before diving in, here's what matters when choosing a webhook testing tool:

Performance - How fast can you start capturing webhooks?
Ease of integration - Simple setup or complex configuration?
Documentation - Clear docs make or break dev experience
Pricing - Free tier? Subscription? Pay-per-use?
Community/Support - Active development and responsive support?

Now let's look at each tool.

1. 🥇 Webhook Debugger & Logger

Link: https://apify.com/ar27111994/webhook-debugger-logger

Pricing: $10/1,000 webhooks (pay-per-event)

Quick start difficulty: Easy ✅

What it does:
A serverless Apify Actor designed specifically for webhook debugging. Generates temporary webhook URLs and logs every incoming request with complete metadata.

Key features:

✅ CIDR IP Whitelisting & Bearer Auth 🛡️
✅ Sensitive Header Masking (Auth/Key scrubbing)
✅ Real-time request capture (SSE Stream)
✅ No localhost tunnelling needed
✅ /replay API for testing idempotency
✅ JSON Schema validation
✅ Custom status codes & latency simulation (Standby Mode)
✅ Export as JSON/CSV

Developer experience highlights:

Zero setup - start capturing in 30 seconds
Complete raw data access (crucial for signature debugging)
Programmatic API for CI/CD integration
Enterprise features (IP whitelisting, API key auth)

Best for:

Launch Week Survival: Handling burst traffic for high-stakes releases.
Stripe & Shopify integrations: Using pre-configured "Launch Packs."
Testing signature verification: Accessing raw request bodies.
Enterprise Security: CIDR whitelisting and header scrubbing.
API mocking: Simulating slow or faulty 3rd party APIs.

Code example:

# Start Actor and get webhook URL
# https://<run-id>.runs.apify.net/webhook/wh_abc123

# Send test webhook
curl -X POST https://<run-id>.runs.apify.net/webhook/wh_abc123 \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.success", "amount": 9999}'

# Replay captured webhook
curl -X POST https://<run-id>.runs.apify.net/replay/wh_abc123 \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://myapp.com/webhook"}'

Pros:

Pay only for what you use
Advanced features (replay, mocking, validation)
Persistent URLs (1-72 hours configurable)
No tunnelling complexity

Cons:

Requires Apify account (free tier available)
Not as well-known as ngrok

2. 🏠 ngrok

Link: https://ngrok.com

Pricing: Free / $8/month (Basic) / $20/month (Pro)

Quick start difficulty: Moderate

What it does:
Creates secure tunnels to expose your localhost to the internet. The gold standard for local webhook development.

Best feature: Request inspection with replay

Code example:

# Install ngrok
brew install ngrok

# Start tunnel to localhost:3000
ngrok http 3000

# Get public URL like: https://abc123.ngrok.io

Pros:

Industry standard
Robust and reliable
Request inspection included
Replay functionality

Cons:

Free URLs change every session
Requires CLI installation
Monthly subscription for persistent URLs
Focused on tunnelling, not debugging

Best for: Local development when you need webhooks to hit your localhost server.

3. 🎯 Webhook.site

Link: https://webhook.site

Pricing: Free (limited) / $10/month (Pro)

Quick start difficulty: Easy ✅

What it does:
Instant webhook URLs for quick inspections. No account needed (free tier).

Best feature: Instant setup - open site, get URL

Pros:

Zero setup on free tier
Clean, simple UI
Good for quick tests

Cons:

Some features require Custom Actions (paid)
Subscription-based pricing

Best for: One-off tests when you just need to see what's being sent.

4. 🏢 Hookdeck

Link: https://hookdeck.com

Pricing: Free tier / $70/month (Pro)

Quick start difficulty: Complex

What it does:
Enterprise webhook management platform with routing, retries, and transformation.

Best feature: Production-grade reliability with automatic retries

Pros:

Built for production scale
Automatic retries and error handling
Payload transformation
Extensive logging

Cons:

Expensive ($70/month minimum)
Overkill for simple debugging
Complex setup

Best for: Enterprise teams managing thousands of webhooks daily.

5. 💰 RequestBin

Link: https://requestbin.com

Pricing: Free (hosted) / Self-hosted

Quick start difficulty: Easy ✅

What it does:
Creates temporary bins to capture HTTP requests. Minimalist and straightforward.

Best feature: Completely free, no account required

Pros:

Free (hosted version)
Open source
Simple interface

Cons:

URLs expire quickly (20 requests or 48 hours)
Very basic features
No replay or mocking

Best for: Simple, disposable testing.

6. 🎭 Beeceptor

Link: https://beeceptor.com

Pricing: Free tier / $10/month (Pro)

Quick start difficulty: Easy

What it does:
Mock API endpoints with custom responses. Useful for testing client behaviour.

Best feature: Custom response rules

Pros:

Great for API mocking
Custom responses
Request logging

Cons:

Not webhook-specific
Limited free tier

Best for: API mocking when you need custom responses.

Comparison Table

Feature	Webhook Debugger	ngrok	Webhook.site	Hookdeck	RequestBin	Beeceptor
Replay	✅	✅	✅	✅	❌	❌
Mocking	✅	❌	✅	✅	❌	✅
Schema Validation	✅	❌	✅*	✅	❌	❌
URL Duration	1-72h	Paid	168h (7 days)	Unlimited	48h	Limited
API Access	✅	✅	✅	✅	❌	✅
Free Tier	✅	✅	✅	✅	✅	✅
Price (Paid)	$10/1k events	$8/mo	$9/mo	$70/mo	Free	$10/mo

*Via Custom Actions

My Recommendation

For most developers:

Webhook Debugger & Logger offers the best balance. Pay-per-event pricing means you only pay for what you use, and features like replay, mocking, and schema validation make serious debugging possible.

For local development:

ngrok is still the go-to when you need localhost exposure.

For quick tests:

Webhook.site or RequestBin work fine for simple inspections.

For enterprise:

Hookdeck provides production reliability at enterprise pricing.

Conclusion

I personally saved 10+ hours per week switching to Webhook Debugger for Stripe and GitHub integrations. The ability to replay requests and validate schemas automatically has been a game-changer.

What webhooks are you debugging? Drop a comment! 💬