DEV Community: Anonymily

How to Test SendGrid Webhooks Locally

Anonymily — Sun, 19 Jul 2026 10:01:38 +0000

The Challenge of Testing SendGrid Webhooks Locally

SendGrid webhooks are powerful—they let you track email opens, bounces, clicks, and delivery status in real time. But testing them locally is frustrating. Your webhook endpoint lives at localhost:3000, which SendGrid can't reach from the internet. You're left juggling ngrok tunnels, managing temporary URLs, or pushing code to staging just to verify that a bounce event triggers the right database update.

The core problem: test SendGrid webhooks locally without exposing your machine, and without losing the ability to inspect and replay payloads when something breaks. This article walks through three production-ready approaches—from manual tunneling to local webhook relaying—so you can debug with confidence.

Prerequisites

SendGrid account with API key (free tier works)
Node.js 16+ and npm or yarn installed
Express.js or similar HTTP server running locally (we'll use Express in examples)
Understanding of HMAC-SHA256 verification (SendGrid signs all webhooks; you must validate the signature)
curl or Postman for manual testing

Testing SendGrid Event Webhooks Locally: Three Approaches

Approach 1: Manual Tunnel with ngrok (Quick, Temporary)

If you need to test right now and don't mind a temporary URL:

# Terminal 1: Start ngrok tunnel
ngrok http 3000

# Copy the forwarding URL, e.g., https://abc123.ngrok.io

Then in SendGrid dashboard:

Go Settings → Event Webhooks
Paste https://abc123.ngrok.io/webhooks/sendgrid as the endpoint
Enable event types (Bounce, Click, Open, etc.)
Click Test Your Integration

Your local Express server will receive the test event. But ngrok URLs regenerate on restart, and managing multiple test sessions gets tedious. Anonymily vs ngrok compares the trade-offs.

Approach 2: Stable Local Endpoint with Anonymily (Recommended for Development)

For a persistent, replayable webhook endpoint that survives restarts:

# Terminal 1: Start Anonymily listener
npx @anonymilyhq/cli listen 3000

# Output:
# Listening on http://localhost:3000
# Webhook endpoint: https://api.anonymily.com/h/my-sendgrid-test
# Forwarding events via Server-Sent Events

Settings → Event Webhooks
Paste https://api.anonymily.com/h/my-sendgrid-test
Enable Bounce, Delivery, Open, Click
Save and test

Now SendGrid sends events to Anonymily's cloud, which forwards them 1:1 to your localhost over Server-Sent Events. Your local handler receives the full payload:

// server.js
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// SendGrid webhook handler
app.post('/webhooks/sendgrid', (req, res) => {
  const signature = req.headers['x-twilio-email-signature'];
  const timestamp = req.headers['x-twilio-email-timestamp'];
  const rawBody = req.rawBody; // Must capture raw body before JSON parsing

  // Verify HMAC signature
  const webhookKey = process.env.SENDGRID_WEBHOOK_KEY;
  const data = timestamp + req.body;
  const hash = crypto
    .createHmac('sha256', webhookKey)
    .update(data)
    .digest('base64');

  if (hash !== signature) {
    console.error('Signature mismatch');
    return res.status(401).send('Unauthorized');
  }

  // Process events
  const events = Array.isArray(req.body) ? req.body : [req.body];
  events.forEach(event => {
    console.log(`Event: ${event.event}`, event);
    // Update database, trigger alerts, etc.
  });

  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Listening on :3000'));

Key detail: SendGrid sends the signature as x-twilio-email-signature and timestamp as x-twilio-email-timestamp. You must reconstruct the signed data as timestamp + request_body_string (not JSON), then compare the base64-encoded HMAC-SHA256 hash.

Anonymily captures all payloads in the cloud even when localhost is down, and the free tier includes 48-hour history and single replay. Pro ($9/month) adds modify-and-replay, re-signing, and signature verification helpers—useful when you need to test edge cases without waiting for SendGrid to resend.

Approach 3: Synthetic Test Events (Pro Feature)

If you're on Anonymily Pro, you can generate provider-signed test events without triggering real SendGrid sends:

# With Anonymily MCP server in Claude Code / Cursor
# You can ask the AI to create a synthetic bounce event,
# and it will be signed with SendGrid's keys

This is valuable for testing error paths (e.g., what happens when a bounce event arrives with a malformed recipient address) without polluting your SendGrid logs.

Common Errors and Fixes

Error 1: "Signature mismatch" on Every Event

Root cause: You're signing the JSON-parsed request body instead of the raw HTTP body string.

SendGrid constructs the signature using the raw bytes sent over the wire. If Express or your framework parses JSON first, you lose that raw data.

Fix: Capture the raw body before JSON parsing:

// Middleware to capture raw body
app.use(express.json({ verify: (req, res, buf) => {
  req.rawBody = buf.toString('utf8');
}}));

// Then in your handler:
const data = timestamp + req.rawBody;
const hash = crypto.createHmac('sha256', webhookKey).update(data).digest('base64');

Error 2: "Endpoint returned 5xx; retrying"

Root cause: Your handler is throwing an exception or not returning a 2xx status quickly.

SendGrid retries failed webhooks exponentially. If your database is slow or a dependency times out, SendGrid may mark the endpoint as unhealthy.

Fix: Add error handling and respond immediately:

app.post('/webhooks/sendgrid', async (req, res) => {
  // Verify signature first
  if (!isValidSignature(req)) {
    return res.status(401).send('Unauthorized');
  }

  // Respond immediately
  res.status(200).send('OK');

  // Process events asynchronously
  setImmediate(async () => {
    try {
      const events = Array.isArray(req.body) ? req.body : [req.body];
      for (const event of events) {
        await db.events.insert(event);
      }
    } catch (err) {
      console.error('Event processing failed:', err);
      // Log to monitoring system, trigger alert
    }
  });
});

Frequently Asked Questions

Q: Do I need to validate the SendGrid webhook signature every time?

A: Yes. Signature verification is non-negotiable—it proves the event came from SendGrid, not an attacker. Use HMAC-SHA256 with your webhook key. Always validate before processing.

Q: Can I test SendGrid webhooks without a public URL?

A: Yes. Use a stable local endpoint like Anonymily, which provides a cloud-based URL that forwards events to localhost over Server-Sent Events. Your machine never needs to be publicly reachable.

Q: What's the difference between SendGrid event webhooks and inbound mail webhooks?

A: Event webhooks fire when SendGrid processes an email you sent (bounce, click, open, delivery). Inbound mail webhooks fire when SendGrid receives an email sent to your domain. Both use HMAC signatures; both can be tested locally the same way.

Next Steps

Testing SendGrid webhooks locally is straightforward once you handle signature verification and have a stable endpoint. Start with a tunnel if you're prototyping, but graduate to a persistent local relay for any serious development.

Try npx @anonymilyhq/cli listen 3000 and register the provided endpoint in SendGrid. You'll see payloads arrive instantly, replay them, and catch bugs before they hit production. Visit anonymily.com to explore the free tier or Pro features like signature verification helpers and synthetic events.

How to Test Razorpay Webhooks Locally

Anonymily — Sun, 19 Jul 2026 10:01:29 +0000

The Challenge: Testing Razorpay Webhooks Without Public Infrastructure

Testing Razorpay payment webhooks locally is frustrating. Razorpay's webhook system requires a publicly accessible HTTPS endpoint to deliver payment events—but your localhost isn't reachable from the internet. You're forced to either deploy to staging for every test, use temporary tunnels that break on restart, or skip webhook testing altogether until production. None of these options catch bugs early or let you debug signature verification, payload parsing, or idempotency logic safely.

When you test Razorpay webhooks locally, you need three things: a stable endpoint URL that Razorpay can reach, the ability to replay events without re-triggering payments, and local access to the raw webhook payload for debugging. This guide shows you how to set up all three.

Prerequisites

Razorpay account with API keys (Key ID and Key Secret) from the Razorpay Dashboard
Node.js 16+ and npm installed locally
Express.js or similar HTTP framework (we'll use Express in examples)
curl or Postman to trigger test requests
Understanding of HMAC-SHA256 signature verification (we'll cover it, but familiarity helps)

Setting Up Razorpay Webhook Testing Locally

Step 1: Create a Local Webhook Handler

Start by building a minimal Express server that accepts and logs Razorpay webhooks. This handler will verify the signature and process payment events.

const express = require('express');
const crypto = require('crypto');
const app = express();

// Middleware to capture raw body for signature verification
app.use(express.json({ verify: (req, res, buf) => {
  req.rawBody = buf.toString('utf8');
}}));

const RAZORPAY_KEY_SECRET = process.env.RAZORPAY_KEY_SECRET;

app.post('/webhooks/razorpay', (req, res) => {
  const signature = req.headers['x-razorpay-signature'];
  const body = req.rawBody;

  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', RAZORPAY_KEY_SECRET)
    .update(body)
    .digest('hex');

  if (signature !== expectedSignature) {
    console.error('❌ Signature mismatch');
    return res.status(403).json({ error: 'Invalid signature' });
  }

  console.log('✅ Signature verified');
  console.log('Event:', req.body.event);
  console.log('Payload:', JSON.stringify(req.body, null, 2));

  // Handle specific events
  switch (req.body.event) {
    case 'payment.authorized':
      console.log('Payment authorized:', req.body.payload.payment.entity.id);
      break;
    case 'payment.failed':
      console.log('Payment failed:', req.body.payload.payment.entity.id);
      break;
    case 'payment.captured':
      console.log('Payment captured:', req.body.payload.payment.entity.id);
      break;
    default:
      console.log('Unhandled event:', req.body.event);
  }

  // Acknowledge receipt immediately
  res.status(200).json({ status: 'ok' });
});

app.listen(3000, () => {
  console.log('Webhook server running on http://localhost:3000');
});

Save this as webhook-server.js and start it:

export RAZORPAY_KEY_SECRET="your_key_secret_here"
node webhook-server.js

Step 2: Expose Your Localhost to Razorpay Using a Stable Tunnel

Your local server is not accessible from the internet. You need a tunnel that forwards Razorpay's requests to localhost. Unlike temporary tools that break on restart, use a stable named endpoint:

npx @anonymilyhq/cli listen 3000

This command:

Captures webhooks in the cloud at a stable HTTPS endpoint like https://api.anonymily.com/h/your-endpoint-name
Forwards them 1:1 to http://localhost:3000 over Server-Sent Events
Survives restarts and redeploys (the endpoint URL stays the same)
Works even if localhost is temporarily down (requests queue in the cloud)

The output shows your public endpoint URL. Copy it.

Step 3: Register the Webhook Endpoint in Razorpay Dashboard

Log in to Razorpay Dashboard
Navigate to Settings → Webhooks
Click Add New Webhook
Paste your Anonymily endpoint URL (e.g., https://api.anonymily.com/h/your-endpoint-name) into the URL field
Select events to subscribe to:
- payment.authorized
- payment.failed
- payment.captured
Click Create Webhook

Razorpay will send a test event. If your handler is running and the tunnel is active, you'll see the signature verification succeed and the event logged locally.

Step 4: Trigger a Test Payment and Observe the Webhook

Create a test payment using Razorpay's test mode (use card 4111 1111 1111 1111 with any future expiry and CVV). When the payment completes, Razorpay sends a webhook to your registered endpoint. The Anonymily tunnel captures it and forwards it to your local handler.

You should see output like:

✅ Signature verified
Event: payment.captured
Payload: {
  "event": "payment.captured",
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_1234567890abcd",
        "amount": 50000,
        "currency": "INR",
        "status": "captured"
      }
    }
  }
}

Common Errors and Fixes

Error 1: `❌ Signature mismatch`

Root Cause:

The x-razorpay-signature header doesn't match your computed HMAC. This usually happens because:

You're hashing the parsed JSON instead of the raw request body
Your RAZORPAY_KEY_SECRET is wrong or truncated
The request body was modified before hashing

Fix:

Always capture the raw body before JSON parsing. Express's default express.json() discards the raw bytes. Use the verify callback:

app.use(express.json({ verify: (req, res, buf) => {
  req.rawBody = buf.toString('utf8');
}}));

Then hash req.rawBody, not JSON.stringify(req.body).

Error 2: `ECONNREFUSED: Connection refused` (localhost:3000)

Root Cause:

Your webhook handler crashed, wasn't started, or is listening on a different port. The tunnel tries to forward the webhook but can't connect.

Fix:

Verify the handler is running: curl http://localhost:3000/webhooks/razorpay should not return "Connection refused"
Check the port matches your tunnel command: npx @anonymilyhq/cli listen 3000 must match your Express app.listen(3000)
Check for startup errors in your handler logs (e.g., missing RAZORPAY_KEY_SECRET env var)

Frequently Asked Questions

Q: Can I replay a webhook without re-triggering a payment?

A: Yes. After a webhook is captured, you can replay it to test error handling or idempotency logic. With the free tier, you get one replay. Pro tier ($9/month) adds modify-and-replay: change the payload, re-sign it with your key, and replay—all within the Anonymily dashboard. This is invaluable for testing edge cases like duplicate payment IDs or refund scenarios.

Q: How do I know if my signature verification is correct?

A: The honest way: capture a real webhook from Razorpay, log both the header signature and your computed signature, and compare them. If they match, your logic is correct. Pro tier includes a signature verification helper that validates your implementation against provider-signed synthetic events—Razorpay included—without needing to trigger real payments.

Q: What's the difference between testing locally and in production?

A: Locally, you control the environment and can replay events infinitely. In production, webhooks arrive once, in order, with no replay. Test idempotency (handling the same event twice), error recovery (what if your handler times out?), and signature verification locally. Production is for monitoring and alerting when things go wrong.

Next Steps

Set up your local Razorpay webhook handler now:

npx @anonymilyhq/cli listen 3000

Your stable endpoint URL appears in the output. Register it in Razorpay Dashboard, trigger a test payment, and watch the webhook flow into your local logs. For replay, signature verification helpers, and provider-signed synthetic events, explore Anonymily Pro.

If you're also testing webhooks from other providers, see Test Webhooks Locally Without ngrok for a broader strategy. For deep dives into signature verification across providers, read Mastering Webhook Signature Verification.

Webhook 400 Bad Request: Debugging & Fixes

Anonymily — Sun, 19 Jul 2026 10:01:18 +0000

The 400 Bad Request Problem

A webhook 400 bad request error hits your logs at 2 AM. Your integration was working yesterday. The provider (Stripe, GitHub, Shopify) is sending data, but your handler is rejecting it with HTTP 400. You've checked the endpoint URL. You've verified the domain. But the webhook malformed request keeps coming back.

This is one of the most frustrating webhook integration failures because the error message is intentionally vague—HTTP 400 means "I couldn't parse or validate what you sent," but not why. The root cause could be anywhere: raw body parsing, header mismatches, JSON encoding, signature verification, or middleware order. This guide walks you through the exact debugging steps and fixes that work.

Prerequisites

A running backend service (Node.js, Python, Go, etc.) with a webhook handler already defined
Access to your webhook provider's documentation and request logs (Stripe Dashboard, GitHub Settings, etc.)
Basic familiarity with HTTP headers, JSON, and raw request bodies
A tool to inspect incoming webhook payloads (curl, Postman, or a local webhook inspector)
Understanding of your framework's middleware execution order (Express, Fastify, Django, Flask, etc.)

Debugging Webhook 400 Bad Request Errors: Step-by-Step

Step 1: Capture the Actual Request

The first rule: never debug blind. You need to see the exact bytes your handler received.

# If you're running locally, start a simple echo server to see raw requests
nc -l 3000

Or use a webhook inspector to capture the full request (headers, body, method):

npx @anonymilyhq/cli listen 3000

This command gives you a stable endpoint URL like https://api.anonymily.com/h/my-endpoint that captures all incoming webhooks and forwards them to your local handler. You'll see the exact payload, headers, and timestamps in the web dashboard—crucial for debugging.

Step 2: Check Content-Type and Raw Body Handling

The most common cause of webhook 400 errors is raw body parsing. Many providers (Stripe, GitHub, Twilio) require the raw, unparsed request body for signature verification. If your middleware parses JSON before you extract the raw body, the signature check fails.

// ❌ WRONG: JSON middleware runs first, raw body is lost
app.use(express.json());
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  // req.body is parsed, but raw bytes are gone
  const verified = verifySignature(req.body, signature); // FAILS
  res.sendStatus(200);
});

// ✅ CORRECT: Capture raw body before JSON parsing
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const rawBody = req.body; // Still raw Buffer
  const verified = verifySignature(rawBody, signature); // Works
  const parsed = JSON.parse(rawBody);
  res.sendStatus(200);
});

Step 3: Validate JSON Encoding

Some providers send Content-Type: application/json; charset=utf-8. Others send application/x-www-form-urlencoded with JSON nested inside. Check your provider's docs.

# Python example: handle both encodings
from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    content_type = request.headers.get('Content-Type', '')

    if 'application/json' in content_type:
        payload = request.get_json()
    elif 'application/x-www-form-urlencoded' in content_type:
        # Some providers send JSON in a form field
        payload = json.loads(request.form.get('payload', '{}'))
    else:
        return 'Unsupported Content-Type', 400

    if not payload:
        return 'Empty or invalid JSON', 400

    # Process payload
    return '', 200

Step 4: Verify Signature Headers

Providers sign webhooks to prove authenticity. A missing or mismatched signature header causes 400 errors if your handler rejects unsigned requests.

// Stripe example: signature in X-Stripe-Signature header
const crypto = require('crypto');

function verifyStripeSignature(rawBody, signature, secret) {
  const [timestamp, signedContent] = signature.split(',').map(s => s.split('=')[1]);
  const computed = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody.toString()}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signedContent)
  );
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-stripe-signature'];
  if (!signature) {
    return res.status(400).json({ error: 'Missing signature header' });
  }

  try {
    if (!verifyStripeSignature(req.body, signature, process.env.STRIPE_WEBHOOK_SECRET)) {
      return res.status(400).json({ error: 'Invalid signature' });
    }
  } catch (err) {
    return res.status(400).json({ error: 'Signature verification failed' });
  }

  res.json({ received: true });
});

Step 5: Check Endpoint Configuration

Ensure your webhook endpoint URL is exactly what the provider expects:

Protocol: HTTPS (not HTTP, unless testing locally)
Port: 443 for HTTPS, 80 for HTTP. Don't include :443 in the URL
Path: Match the exact path registered with the provider
Query parameters: Some providers allow them; others reject URLs with query strings

# Test your endpoint with curl, mimicking the provider's request
curl -X POST https://yourdomain.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Signature: your-signature-here" \
  -d '{"event":"test","data":{}}'

Common Errors and Fixes

Error 1: "SyntaxError: Unexpected token < in JSON at position 0"

Root cause: Your endpoint is returning HTML (likely a 404 page or error page) instead of JSON. The provider is sending a valid webhook, but your server is routing it incorrectly.

Fix:

// Verify your route is registered BEFORE generic error handlers
app.post('/webhook', (req, res) => {
  res.json({ received: true });
});

// Generic 404 handler comes AFTER specific routes
app.use((req, res) => {
  res.status(404).json({ error: 'Not found' });
});

// Test the route exists
console.log(app._router.stack.filter(r => r.route?.path === '/webhook'));

Error 2: "413 Payload Too Large" or "Unexpected end of JSON input"

Root cause: Your middleware has a size limit that's too small, or the body parser is truncating large payloads.

Fix:

// Increase payload size limits
app.use(express.json({ limit: '50mb' }));
app.use(express.raw({ type: 'application/json', limit: '50mb' }));

// For Fastify
fastify.register(require('@fastify/raw-body'), { limit: '50mb' });

Frequently Asked Questions

Q: Why does my webhook handler return 200 but the provider shows it as failed?

A: The provider likely has a timeout (usually 5–30 seconds). If your handler takes longer, the provider cancels the request mid-response. Return 200 immediately, then process the payload asynchronously in a background job. Also verify you're actually returning 200 and not a 200 with an error body that the provider interprets as failure.

Q: Can I test webhook 400 errors locally without deploying?

A: Yes. Use a webhook inspector like Anonymily to capture payloads and replay them. The command npx @anonymilyhq/cli listen 3000 forwards webhooks to your local handler, and the dashboard lets you inspect exactly what failed. You can also replay requests to test fixes without waiting for the provider to retry.

Q: How do I know if the issue is my code or the provider's webhook?

A: Check your provider's webhook logs (Stripe Dashboard, GitHub Settings > Webhooks, etc.). If the provider shows a successful send but your server logs show nothing, the issue is networking or routing. If the provider shows a failed send, capture the request with a webhook inspector to see what was actually sent.

Next Steps

Start by capturing your next webhook with a local inspector. Run npx @anonymilyhq/cli listen 3000 and check the dashboard at https://anonymily.com—you'll see the exact headers, body, and timestamps. This single step eliminates 80% of guesswork.

If you're integrating with GitHub, Stripe, or Shopify, test webhooks locally without ngrok to avoid port-forwarding complexity. For production, remember that Anonymily is a dev tool; for production receive-at-scale with retries and SLA, use Hookdeck or Svix.

The 400 error almost always traces back to raw body handling, signature verification, or routing. Debug methodically, capture the actual request, and you'll fix it in minutes.

How to Test Twilio Webhooks Locally

Anonymily — Fri, 10 Jul 2026 10:14:34 +0000

The Problem: Twilio Webhooks Won't Hit Your Localhost

When you're building a Twilio integration—whether handling incoming SMS, voice callbacks, or call status updates—you need to test those webhooks against your local development environment. But Twilio's servers can't reach http://localhost:3000. Your machine isn't publicly routable on the internet. You need a way to expose your local webhook handler to Twilio's infrastructure, capture the payloads, inspect them, and debug failures without deploying to staging every time.

This is where most developers hit a wall: they either spin up a staging environment (slow feedback loop) or struggle with outdated tunneling solutions that break on restart. Testing Twilio webhooks locally requires both a stable public endpoint and a reliable way to forward those requests back to your machine. Let's walk through the real approaches.

Prerequisites

Node.js (v14+) and npm installed locally
Twilio account with an active phone number (free trial account works)
Basic Express or Fastify knowledge — you'll be writing a simple webhook handler
Postman or curl — for manual testing before Twilio integration
Understanding of HMAC-SHA1 — Twilio signs requests; you'll verify them

Setting Up and Testing Twilio Webhooks Locally

Step 1: Create a Local Webhook Handler

Start by building a minimal Express server that accepts Twilio's webhook POST requests. Twilio sends form-encoded data, so you'll need the appropriate middleware.

const express = require('express');
const twilio = require('twilio');
const app = express();

app.use(express.urlencoded({ extended: false }));

// Twilio auth token from your account
const TWILIO_AUTH_TOKEN = process.env.TWILIO_AUTH_TOKEN;

// Middleware to verify Twilio request signature
const validateTwilioRequest = (req, res, next) => {
  const twilioSignature = req.headers['x-twilio-signature'];
  const url = `https://${req.get('host')}${req.originalUrl}`;

  // Reconstruct the request body as Twilio does
  const params = req.body;

  const isValid = twilio.validateRequest(
    TWILIO_AUTH_TOKEN,
    twilioSignature,
    url,
    params
  );

  if (!isValid) {
    return res.status(403).send('Twilio request signature validation failed');
  }

  next();
};

// SMS webhook endpoint
app.post('/sms', validateTwilioRequest, (req, res) => {
  const { From, Body, MessageSid } = req.body;

  console.log(`SMS from ${From}: ${Body} (SID: ${MessageSid})`);

  // Your business logic here
  const twiml = new twilio.twiml.MessagingResponse();
  twiml.message('Thanks for your message!');

  res.type('application/xml').send(twiml.toString());
});

// Call status webhook endpoint
app.post('/call-status', validateTwilioRequest, (req, res) => {
  const { CallSid, CallStatus, From } = req.body;

  console.log(`Call ${CallSid} from ${From} is now ${CallStatus}`);

  res.send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

This handler:

Validates every incoming request using Twilio's signature verification
Logs SMS and call status events
Returns appropriate TwiML or status responses

Step 2: Expose Your Localhost to the Internet

You need a stable public URL that Twilio can POST to. This is where local development gets tricky. Several options exist:

Option A: Traditional HTTP Tunnel (ngrok, LocalTunnel)

# Using ngrok
ngrok http 3000

# Output:
# Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

The problem: ngrok's free tier generates a new URL every time you restart. You'd have to update Twilio's webhook URL manually each session.

Option B: Stable Endpoint with Anonymily

Anonymily vs ngrok — Anonymily provides a stable named endpoint that survives restarts:

npx @anonymilyhq/cli listen 3000

This command:

Creates a persistent URL: https://api.anonymily.com/h/<endpoint-name>
Forwards all incoming webhooks to your local server over Server-Sent Events
Captures requests even if localhost is temporarily down
Provides a web UI to inspect payloads

Step 3: Configure Twilio Webhook URLs

Once your local handler is running and exposed, configure Twilio to send webhooks to your public endpoint.

In the Twilio Console:

Navigate to Phone Numbers → your active number
Under Messaging, set Webhook URL to your public endpoint: https://api.anonymily.com/h/my-twilio-sms (or your ngrok URL)
Set HTTP Method to POST
Under Voice, set Webhook URL for call status callbacks similarly

# Example: if using Anonymily
# SMS Webhook URL: https://api.anonymily.com/h/twilio-sms-handler
# Call Status URL: https://api.anonymily.com/h/twilio-call-status

Step 4: Test with Real Twilio Events

Send yourself an SMS to your Twilio number, or make a test call. Your local handler will receive the webhook.

# Terminal 1: Start your local handler
node webhook-handler.js

# Terminal 2: Start the tunnel (Anonymily example)
npx @anonymilyhq/cli listen 3000

# Terminal 3: Send a test SMS from any phone to your Twilio number
# Watch the logs in Terminal 1 for incoming webhook

You should see output like:

SMS from +1234567890: Hello World (SID: SM1234567890abcdef)

Step 5: Inspect and Replay Payloads

If you're using Anonymily, open the web dashboard to see all captured webhooks. You can inspect the raw payload, headers, and signature. The free tier includes unlimited single replay, so you can fix a bug and re-trigger the webhook without sending another SMS.

For mastering webhook signature verification, ensure your validation logic matches Twilio's expectations: the signature is HMAC-SHA1 of the URL + form-encoded body, using your auth token as the key.

Common Errors and Fixes

Error 1: "Twilio request signature validation failed"

Exact error message:

403 Forbidden: Twilio request signature validation failed

Root cause:
The signature validation is failing because:

The URL used in validation doesn't match the URL Twilio sent the request to (protocol mismatch, missing query params, etc.)
The auth token is wrong or not loaded from the environment
The request body was parsed incorrectly (form encoding issues)

Fix:

// Ensure you're using the FULL URL, including scheme and host
const url = `https://${req.get('host')}${req.originalUrl}`;

// Log the URL and signature for debugging
console.log('Validating URL:', url);
console.log('Twilio signature:', req.headers['x-twilio-signature']);

// Verify auth token is loaded
if (!TWILIO_AUTH_TOKEN) {
  throw new Error('TWILIO_AUTH_TOKEN env var not set');
}

// If using a tunnel, ensure the URL matches what Twilio sees
// (e.g., https://api.anonymily.com/h/endpoint, not localhost)

Error 2: "Cannot read property 'validateRequest' of undefined"

Exact error message:

TypeError: Cannot read property 'validateRequest' of undefined

Root cause:
The twilio package wasn't imported, or an older version is installed that doesn't include validateRequest.

Fix:

npm install twilio@latest

Then verify the import:

const twilio = require('twilio');

// Confirm validateRequest is available
console.log(typeof twilio.validateRequest); // Should be 'function'

Frequently Asked Questions

Q: How do I test Twilio SMS webhooks without sending real SMS?

A: Use Twilio's TwiML Bins or a tool like Anonymily with synthetic events (Pro tier) to generate provider-signed test payloads. For manual testing, use curl with a manually constructed form-encoded body and manually calculated HMAC signature, though this is tedious. The easiest path: send a real SMS to your Twilio number (free tier includes credits).

Q: What's the difference between testing locally with ngrok vs. a stable endpoint?

A: ngrok's free tier generates a new URL on every restart, requiring manual Twilio configuration updates. A stable endpoint like Anonymily persists across restarts, reducing friction during development. See the detailed comparison for trade-offs.

Q: How do I handle Twilio webhook retries if my local server crashes?

A: Twilio will retry failed webhooks for a limited time. With Anonymily, webhooks are captured in the cloud even if localhost is down, then replayed when your server restarts. With ngrok alone, retries are lost. For production, use a proper webhook gateway like Hookdeck that guarantees delivery.

Getting Twilio webhooks working locally doesn't have to mean constant staging deploys or manual URL shuffling. Try npx @anonymilyhq/cli listen 3000 to expose your localhost with a stable endpoint, inspect payloads in real time, and replay events instantly. Head to anonymily.com to get started.

Webhook Signature Mismatch: Root Causes & Solutions

Anonymily — Fri, 10 Jul 2026 10:13:56 +0000

The Silent Killer: Why Webhook Signature Mismatch Errors Happen

A webhook arrives at your endpoint, but the signature verification fails. Your handler rejects it. The provider's retry queue fires again. Logs fill with cryptic "signature verification failed" messages, and you're left wondering: Is the payload corrupted? Did I store the secret correctly? Is my clock skewed?

The webhook signature mismatch error is one of the most frustrating integration bugs because it straddles two worlds—the provider's signing logic and your validation code—with no visibility into either. You can't see the raw bytes the provider signed. You can't replay the exact request. And by the time you realize the issue, you've already lost events. This guide walks you through the root causes and gives you concrete debugging steps to resolve it.

Prerequisites

A webhook provider account (GitHub, Stripe, Shopify, or similar) with webhook configuration access
Node.js or Python installed locally; examples use both
Postman or curl for manual testing
Basic cryptography knowledge: familiarity with HMAC-SHA256 and hex encoding
Access to your webhook handler code and environment variables (secret key storage)

Debugging and Fixing Webhook Signature Mismatch Errors

Step 1: Understand Your Provider's Signing Algorithm

Every webhook provider documents their signature scheme. Most use HMAC-SHA256, but the details vary:

GitHub: Signs with HMAC-SHA256(secret, request_body), delivers as X-Hub-Signature-256 header in format sha256=<hex>
Stripe: Signs with HMAC-SHA256(secret, timestamp.payload), delivers as t=<timestamp>,v1=<signature> in Stripe-Signature header
Shopify: Signs with HMAC-SHA256(secret, raw_body), delivers as base64-encoded X-Shopify-Hmac-SHA256 header

Action item: Find your provider's webhook documentation and copy the exact signing formula. This is non-negotiable.

Step 2: Capture the Exact Request Body

The most common cause of signature mismatch is parsing the body incorrectly. Webhook providers sign the raw bytes, not the parsed JSON. If you parse and re-stringify, whitespace differences will break the signature.

Here's the wrong way (Express):

// ❌ WRONG: body-parser has already parsed the body
app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const payload = req.body; // Already parsed—original bytes lost

  // This will fail because we're signing the parsed object, not raw bytes
  const hash = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');

  res.status(400).send('Signature mismatch');
});

Here's the right way (Express with raw body capture):

const express = require('express');
const crypto = require('crypto');

const app = express();

// Capture raw body before parsing
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const rawBody = req.body; // Buffer with original bytes

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const incomingSignature = signature.replace('sha256=', '');

  if (!crypto.timingSafeEqual(
    Buffer.from(incomingSignature),
    Buffer.from(expectedSignature)
  )) {
    return res.status(401).send('Signature verification failed');
  }

  // Safe to parse now
  const payload = JSON.parse(rawBody);
  console.log('Verified webhook:', payload);
  res.status(200).send('OK');
});

Key detail: Use crypto.timingSafeEqual() to prevent timing attacks. Never use === for signature comparison.

Step 3: Verify Secret Storage and Encoding

Secrets are often stored as hex strings or base64, but signed as raw bytes. A mismatch here is invisible.

import hmac
import hashlib
import os
from base64 import b64decode

# ❌ WRONG: Treating hex string as raw bytes
secret_hex = os.getenv('WEBHOOK_SECRET')  # e.g., "abc123def456"
signature = hmac.new(
    secret_hex.encode(),  # Signing the hex representation, not the bytes!
    msg=raw_body,
    digestmod=hashlib.sha256
).hexdigest()

# ✅ CORRECT: Decode hex to bytes first
secret_hex = os.getenv('WEBHOOK_SECRET')
secret_bytes = bytes.fromhex(secret_hex)
signature = hmac.new(
    secret_bytes,  # Sign the actual bytes
    msg=raw_body,
    digestmod=hashlib.sha256
).hexdigest()

# Also correct: If stored as base64
secret_b64 = os.getenv('WEBHOOK_SECRET')
secret_bytes = b64decode(secret_b64)
signature = hmac.new(
    secret_bytes,
    msg=raw_body,
    digestmod=hashlib.sha256
).hexdigest()

Check: Log the first 8 characters of your secret (never the full secret) and compare it to what the provider shows in their UI. If they don't match, you've copied the wrong secret.

Step 4: Debug with Logging and Replay

Add detailed logging to your signature verification:

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const rawBody = req.body;

  console.log('Received signature:', signature);
  console.log('Raw body length:', rawBody.length);
  console.log('Raw body (first 100 chars):', rawBody.toString().slice(0, 100));

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  console.log('Expected signature:', expectedSignature);
  console.log('Match:', signature === `sha256=${expectedSignature}`);

  // ... rest of verification
});

Once you identify the mismatch, use Test Webhooks Locally Without ngrok to capture the exact webhook and replay it locally with modified code. With Anonymily Pro, you can replay with signature verification helpers to isolate the exact byte difference.

Common Errors and Fixes

Error 1: "Signature verification failed" on Every Webhook

Root cause: The raw body is being consumed by middleware before you capture it.

Exact error message:

Signature verification failed: incoming=sha256=abc123... expected=sha256=def456...

Fix: Ensure middleware captures the raw body before parsing:

// Middleware order matters!
app.use(express.raw({ type: 'application/json' }));  // First
app.use(express.json());  // Second (for other routes)

app.post('/webhook', (req, res) => {
  // req.body is still a Buffer here
});

If you're using a framework like Fastify, use bodyLimit and rawBody options:

const fastify = require('fastify');

const app = fastify({
  bodyLimit: 1048576,
});

app.post('/webhook', async (request, reply) => {
  const signature = request.headers['x-hub-signature-256'];
  const rawBody = request.rawBody;  // Fastify provides this

  // Verify signature against rawBody
});

Error 2: "Signature Mismatch" in Production, Not Local

Root cause: Clock skew or timezone differences. Some providers (Stripe, Razorpay) include a timestamp in the signed payload and reject old signatures.

Exact error message:

Signature verification failed: timestamp too old

Fix: Sync your server's clock with NTP:

# Linux/macOS
ntpdate -s time.nist.gov

# Or use timedatectl (systemd)
timedatectl set-ntp true

In your code, allow a small time window (e.g., 5 minutes):

const verifyStripeSignature = (rawBody, signature, secret) => {
  const [timestamp, v1] = signature.split(',').reduce((acc, part) => {
    const [key, val] = part.split('=');
    acc[key === 't' ? 0 : 1] = val;
    return acc;
  }, []);

  const now = Math.floor(Date.now() / 1000);
  const age = now - parseInt(timestamp);

  if (age > 300) {  // 5 minutes
    throw new Error('Timestamp too old');
  }

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(v1),
    Buffer.from(expectedSignature)
  );
};

Frequently Asked Questions

Q: How do I test webhook signature verification locally without the real provider?

A: Use your provider's test/sandbox mode to send real signed webhooks to a local endpoint. If that's not available, manually compute the signature using the provider's algorithm and send it via curl or Postman. For GitHub, Shopify, and other providers, Anonymily Pro includes synthetic provider-signed test events you can replay locally with full signature validation.

Q: Why does my signature match locally but fail in production?

A: The most common cause is middleware order or environment variable differences. Verify that WEBHOOK_SECRET is set identically in both environments (check for trailing whitespace or encoding differences). Also check that your raw body capture middleware runs before any parsing middleware. Use console.log to compare the first 8 hex characters of the secret in both environments.

Q: Can I use a different hash algorithm than HMAC-SHA256?

A: No. Your provider chose HMAC-SHA256 for a reason—it's the industry standard. If your provider supports a different algorithm, they'll document it explicitly. Never assume or substitute algorithms; always use exactly what the provider specifies in their webhook documentation.

Signature mismatches are almost always caused by one of three things: raw body capture, secret encoding, or clock skew. Start by logging the exact bytes you're signing and comparing them to the provider's documentation. If you're stuck, try Mastering Webhook Signature Verification for a deeper dive into verification patterns.

For local development and debugging, npx @anonymilyhq/cli listen 3000 captures real webhooks and replays them to your handler—letting you iterate on signature verification without waiting for provider retries. Visit anonymily.com to get started.

How to Test Slack Webhooks Locally

Anonymily — Mon, 06 Jul 2026 13:35:55 +0000

The Challenge of Testing Slack Webhooks Locally

Testing Slack webhooks locally is deceptively tricky. Slack needs to reach your handler over the internet, but your development machine isn't publicly routable. You can't just point Slack at localhost:3000. Most developers either skip proper local testing (risky), deploy to staging (slow iteration), or spin up temporary tunnels (fragile and tedious). The real pain: when a webhook fails silently, you're left guessing whether it's a network issue, a signature mismatch, or a logic bug in your handler.

This guide walks you through testing Slack webhooks locally—from capturing inbound events to verifying signatures and replaying payloads—so you can iterate fast and debug with confidence.

Prerequisites

Node.js (v16+) and npm installed
A Slack workspace where you can create apps (free tier works)
Basic Express or Fastify knowledge (we'll use Express here)
A Slack app already created in your workspace (or ready to create one)
curl or Postman (optional, for manual testing)

How to Test Slack Webhooks Locally: Step-by-Step

Step 1: Create a Slack App and Configure Event Subscriptions

Go to api.slack.com/apps and click Create New App.
Choose From scratch, name it (e.g., "LocalTestBot"), and select your workspace.
In the left sidebar, navigate to Event Subscriptions.
Toggle Enable Events to On.
For now, leave Request URL blank—we'll come back to this once we have a public endpoint.
Under Subscribe to bot events, add events you want to capture (e.g., message.channels, app_mention).
Save changes.

Step 2: Set Up a Local Express Handler

Create a basic Node.js project:

mkdir slack-webhook-test
cd slack-webhook-test
npm init -y
npm install express dotenv

Create server.js:

const express = require('express');
const crypto = require('crypto');
require('dotenv').config();

const app = express();
app.use(express.json());

const SLACK_SIGNING_SECRET = process.env.SLACK_SIGNING_SECRET;

// Middleware to verify Slack request signatures
function verifySlackRequest(req, res, next) {
  const timestamp = req.headers['x-slack-request-timestamp'];
  const signature = req.headers['x-slack-signature'];

  // Prevent replay attacks: request must be within 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return res.status(401).send('Request timestamp too old');
  }

  // Reconstruct the signed content
  const baseString = `v0:${timestamp}:${JSON.stringify(req.body)}`;
  const hmac = crypto
    .createHmac('sha256', SLACK_SIGNING_SECRET)
    .update(baseString)
    .digest('hex');
  const expectedSignature = `v0=${hmac}`;

  if (!crypto.timingSafeEqual(signature, expectedSignature)) {
    return res.status(401).send('Invalid signature');
  }

  next();
}

app.post('/slack/events', verifySlackRequest, (req, res) => {
  const { type, challenge, event } = req.body;

  // Slack sends a challenge request during URL verification
  if (type === 'url_verification') {
    console.log('✓ Slack URL verification received');
    return res.json({ challenge });
  }

  // Handle actual events
  if (type === 'event_callback') {
    console.log('📨 Event received:', event.type);
    console.log('Payload:', JSON.stringify(event, null, 2));
    // Your event handling logic here
  }

  res.json({ ok: true });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Create a .env file:

SLACK_SIGNING_SECRET=your_signing_secret_here
PORT=3000

Get your signing secret from Slack: go to Basic Information on your app page, scroll to App Credentials, and copy the Signing Secret.

Step 3: Expose Your Local Server with a Public Endpoint

Running npx @anonymilyhq/cli listen 3000 creates a stable public URL that forwards Slack webhooks to your local handler:

npx @anonymilyhq/cli listen 3000

This outputs something like:

✓ Listening on http://localhost:3000
✓ Webhook endpoint: https://api.anonymily.com/h/my-endpoint-name
✓ Forwarding to localhost:3000

Copy that endpoint URL.

Step 4: Register the Endpoint with Slack

Go back to your Slack app's Event Subscriptions page.
Paste your endpoint URL (e.g., https://api.anonymily.com/h/my-endpoint-name/slack/events) into Request URL.
Slack will send a challenge request. If your signature verification is correct, Slack marks it as Verified.
Save changes.

Step 5: Trigger and Capture Events

Now trigger a Slack event. For example, if you subscribed to app_mention:

Go to your Slack channel.
Type @YourBotName hello and send.

Check your terminal—you should see the event logged:

📨 Event received: app_mention
Payload: {
  "type": "app_mention",
  "user": "U12345678",
  "text": "<@U87654321> hello",
  "ts": "1699564800.000100",
  ...
}

Step 6: Test Signature Verification

To verify your HMAC logic is solid, manually test with curl. First, generate a valid signature:

// test-signature.js
const crypto = require('crypto');

const secret = 'your_signing_secret_here';
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify({ type: 'event_callback', event: { type: 'message' } });

const baseString = `v0:${timestamp}:${body}`;
const hmac = crypto.createHmac('sha256', secret).update(baseString).digest('hex');
const signature = `v0=${hmac}`;

console.log('Timestamp:', timestamp);
console.log('Signature:', signature);
console.log('Body:', body);

Run it:

node test-signature.js

Then test your endpoint:

curl -X POST https://api.anonymily.com/h/my-endpoint-name/slack/events \
  -H "Content-Type: application/json" \
  -H "X-Slack-Request-Timestamp: 1699564800" \
  -H "X-Slack-Signature: v0=your_calculated_signature" \
  -d '{"type":"event_callback","event":{"type":"message"}}'

You should get a 200 OK response.

Common Errors and Fixes

Error 1: "Invalid Signature"

Error message:

401 Unauthorized: Invalid signature

Root cause: The HMAC calculation doesn't match Slack's signature. Common culprits:

Wrong signing secret (copy-pasted incorrectly)
Request body was modified after receiving it (e.g., Express middleware parsed it twice)
Timestamp check failed (your system clock is off)

Fix:

Double-check your signing secret in .env matches Slack's Basic Information page exactly.
Ensure the raw request body is used for HMAC calculation—don't stringify it again.
Verify your system clock is synchronized: date on Unix, Get-Date on Windows.
Log the baseString and signature before comparison to debug:

console.log('Slack signature:', signature);
console.log('Expected:', expectedSignature);
console.log('Base string:', baseString);

Error 2: "Request timestamp too old"

Error message:

401 Unauthorized: Request timestamp too old

Root cause: Slack's request timestamp is older than 5 minutes (the replay-attack window). This usually happens if:

Your local machine's clock is significantly behind
The request was genuinely delayed (rare with Slack)

Fix:

Sync your system clock.
If testing manually with curl, use the current Unix timestamp:

date +%s  # Unix timestamp

For debugging, temporarily increase the window (but revert before production):

if (Math.abs(now - parseInt(timestamp)) > 3600) { // 1 hour for testing

Frequently Asked Questions

Q: Can I test Slack webhooks without exposing my machine to the internet?

A: Yes. Tools like Anonymily capture webhooks in the cloud and forward them to your local handler over a secure connection. Your machine never accepts inbound connections directly. Test Webhooks Locally Without ngrok covers this in detail.

Q: How do I replay a webhook payload for debugging?

A: Save the JSON payload from your logs, then use curl with the same headers (timestamp and signature). For production-grade replay with signature re-signing, Anonymily's Pro plan includes modify-and-replay. Otherwise, manually reconstruct the HMAC for each test.

Q: What if Slack keeps rejecting my Request URL during verification?

A: Slack sends a url_verification challenge request. Your handler must respond with { "challenge": "<value>" } and pass signature verification. If it fails, check: (1) your signing secret is correct, (2) your endpoint is publicly accessible, (3) your handler returns 200 OK within 3 seconds.

Next Steps

You now have a solid local testing setup for Slack webhooks. The pattern—verify signatures, log payloads, replay for debugging—applies to any webhook provider.

For faster iteration and built-in payload inspection, try npx @anonymilyhq/cli listen 3000 to forward webhooks from a stable public endpoint. Visit anonymily.com to learn more about webhook testing and debugging tools designed for developers.

Webhook Retry Logic: Exponential Backoff Best Practices

Anonymily — Sat, 04 Jul 2026 08:28:42 +0000

Why Webhook Retry Logic Matters

Your webhook handler crashes. The provider sends a request. You miss it. Now what? Without proper webhook retry logic and exponential backoff implementation, transient failures become data loss. The provider might retry once or twice, but if your service is restarting, deploying, or temporarily saturated, those retries disappear into the void. Exponential backoff ensures that when things go wrong—and they will—you get multiple chances to process the event without hammering the provider's infrastructure.

The core problem: naive retry strategies either retry too fast (DDoS-ing yourself and the provider) or too slow (losing time-sensitive data). Exponential backoff strikes the balance by increasing wait time between attempts, giving your system breathing room to recover while respecting the provider's rate limits.

Prerequisites

Node.js 16+ or Python 3.8+ (examples provided in both)
Understanding of HTTP status codes (5xx vs 4xx) and when to retry
A webhook provider account (GitHub, Stripe, or similar) for testing
Familiarity with async/await or Promise-based patterns
A local development environment with curl or Postman

Implementing Webhook Retry Logic with Exponential Backoff

Step 1: Define Your Retry Configuration

Start by establishing clear retry parameters. Not all failures warrant the same treatment—4xx errors (bad request, auth failure) should not retry, while 5xx errors (server error) and network timeouts should.

// retry-config.js
const RETRY_CONFIG = {
  maxRetries: 5,
  initialDelayMs: 1000,      // Start at 1 second
  maxDelayMs: 60000,          // Cap at 60 seconds
  backoffMultiplier: 2,       // Double each time
  jitterFraction: 0.1,        // Add ±10% randomness
  retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  timeoutMs: 10000,           // Per-request timeout
};

function calculateBackoffDelay(attempt, config) {
  // Exponential: 1s, 2s, 4s, 8s, 16s...
  const exponentialDelay = Math.min(
    config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt),
    config.maxDelayMs
  );

  // Add jitter: ±10% to prevent thundering herd
  const jitter = exponentialDelay * config.jitterFraction * (Math.random() - 0.5) * 2;
  return Math.max(0, exponentialDelay + jitter);
}

module.exports = { RETRY_CONFIG, calculateBackoffDelay };

Step 2: Build a Retry Wrapper for Your Handler

Wrap your webhook handler with retry logic that respects the configuration:

// webhook-handler.js
const { RETRY_CONFIG, calculateBackoffDelay } = require('./retry-config');

async function executeWithRetry(fn, context = {}) {
  let lastError;

  for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
    try {
      return await Promise.race([
        fn(),
        new Promise((_, reject) =>
          setTimeout(
            () => reject(new Error('Request timeout')),
            RETRY_CONFIG.timeoutMs
          )
        ),
      ]);
    } catch (error) {
      lastError = error;

      // Don't retry on client errors (4xx)
      if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
        throw error;
      }

      // Don't retry if we've exhausted attempts
      if (attempt === RETRY_CONFIG.maxRetries) {
        break;
      }

      const delayMs = calculateBackoffDelay(attempt, RETRY_CONFIG);
      console.warn(
        `Webhook attempt ${attempt + 1} failed. Retrying in ${delayMs}ms...`,
        { error: error.message, statusCode: error.statusCode }
      );

      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }

  throw new Error(
    `Webhook failed after ${RETRY_CONFIG.maxRetries + 1} attempts: ${lastError.message}`
  );
}

// Example: Stripe webhook handler
async function handleStripeWebhook(event) {
  return executeWithRetry(async () => {
    // Simulate processing: might fail transiently
    const response = await fetch('https://your-api.com/process', {
      method: 'POST',
      body: JSON.stringify(event),
      headers: { 'Content-Type': 'application/json' },
    });

    if (!response.ok) {
      const error = new Error(`HTTP ${response.status}`);
      error.statusCode = response.status;
      throw error;
    }

    return response.json();
  });
}

module.exports = { executeWithRetry, handleStripeWebhook };

Step 3: Implement Python Version (for FastAPI/Django)

# webhook_retry.py
import asyncio
import random
from typing import Callable, Any
from dataclasses import dataclass

@dataclass
class RetryConfig:
    max_retries: int = 5
    initial_delay_ms: int = 1000
    max_delay_ms: int = 60000
    backoff_multiplier: float = 2.0
    jitter_fraction: float = 0.1
    retryable_status_codes: list = None
    timeout_ms: int = 10000

    def __post_init__(self):
        if self.retryable_status_codes is None:
            self.retryable_status_codes = [408, 429, 500, 502, 503, 504]

def calculate_backoff_delay(attempt: int, config: RetryConfig) -> int:
    """Calculate exponential backoff with jitter."""
    exponential_delay = min(
        config.initial_delay_ms * (config.backoff_multiplier ** attempt),
        config.max_delay_ms
    )
    jitter = exponential_delay * config.jitter_fraction * (random.random() - 0.5) * 2
    return max(0, int(exponential_delay + jitter))

async def execute_with_retry(
    fn: Callable,
    config: RetryConfig = None
) -> Any:
    """Execute async function with exponential backoff retry."""
    if config is None:
        config = RetryConfig()

    last_error = None

    for attempt in range(config.max_retries + 1):
        try:
            return await asyncio.wait_for(fn(), timeout=config.timeout_ms / 1000)
        except asyncio.TimeoutError as e:
            last_error = e
            if attempt == config.max_retries:
                raise
        except Exception as e:
            last_error = e
            # Don't retry 4xx errors
            if hasattr(e, 'status_code') and 400 <= e.status_code < 500:
                raise
            if attempt == config.max_retries:
                break

            delay_ms = calculate_backoff_delay(attempt, config)
            print(f"Attempt {attempt + 1} failed. Retrying in {delay_ms}ms...")
            await asyncio.sleep(delay_ms / 1000)

    raise RuntimeError(f"Failed after {config.max_retries + 1} attempts: {last_error}")

Step 4: Test Your Retry Logic Locally

Use Anonymily to capture and replay webhook failures:

# Terminal 1: Start Anonymily listener
npx @anonymilyhq/cli listen 3000

# Terminal 2: Start your webhook handler
node webhook-server.js

# Terminal 3: Simulate a failing webhook
curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"event":"charge.succeeded","id":"ch_123"}'

Anonymily captures the request and forwards it to your handler. If your handler returns 5xx or times out, you can replay it from the Anonymily dashboard to verify your retry logic kicks in.

Common Errors and Fixes

Error 1: Retrying 4xx Errors (Infinite Loop Risk)

Exact Error:

POST /webhook HTTP 400 Bad Request
{
  "error": "Invalid signature"
}

Root Cause: Your retry logic doesn't distinguish between client errors (4xx) and server errors (5xx). Retrying a 400 Bad Request will never succeed—the problem is in your code or the request payload.

Fix:

// ✗ Wrong: retries everything
if (attempt < maxRetries) {
  retry();
}

// ✓ Correct: skip 4xx
if (error.statusCode >= 400 && error.statusCode < 500) {
  throw error; // Fail immediately, don't retry
}
if (attempt < maxRetries) {
  retry();
}

Error 2: Thundering Herd (All Retries Fire Simultaneously)

Exact Error:

[12:00:00] Retry attempt 1 (1000ms)
[12:00:01] Retry attempt 2 (1000ms)
[12:00:02] Retry attempt 3 (1000ms)
[12:00:03] All retries hit at once → server overload

Root Cause: Using fixed delays without jitter. When multiple webhook handlers retry at the same time, they create a synchronized thundering herd that overwhelms your infrastructure.

Fix:

// Add jitter: randomize each retry by ±10%
const jitter = exponentialDelay * 0.1 * (Math.random() - 0.5) * 2;
const finalDelay = exponentialDelay + jitter;
// Results: 900ms, 1100ms, 1900ms, 2100ms, etc. (staggered)

Frequently Asked Questions

Q: Should I retry on network timeout?

A: Yes, absolutely. Timeouts indicate transient unavailability—your handler might be restarting, or the network might be flaky. Exponential backoff gives your system time to recover. However, set a reasonable per-request timeout (5–10 seconds) to avoid hanging indefinitely.

Q: How many retries are enough?

A: 5 retries with exponential backoff (1s, 2s, 4s, 8s, 16s) gives you ~31 seconds of total retry window. Most transient failures resolve within this time. For critical events, increase to 7 retries (~2 minutes). Beyond that, you're likely dealing with a persistent outage—log and alert instead.

Q: Can I use exponential backoff for webhook delivery from my own service?

A: Yes. If you're building a webhook provider, implement exponential backoff on your delivery side. Send to the customer's endpoint with retries, respecting their rate limits. Store failed deliveries in a dead-letter queue after retries are exhausted. Anonymily vs Hookdeck compares production webhook gateways that handle this at scale.

Testing and Debugging Your Implementation

When building webhook retry logic, you'll want to test failure scenarios without waiting for real transient errors. Test Webhooks Locally Without ngrok covers local testing workflows. For GitHub webhooks specifically, How to Test GitHub Webhooks Locally walks through synthetic event generation.

Key debugging tips:

Log every retry attempt with the attempt number, delay, and error reason.
Track retry metrics (success rate after N attempts) to tune your configuration.
Use structured logging (JSON) to correlate retries across multiple handlers.
In production, alert on repeated failures to the same endpoint—it signals a real problem, not transience.

Ready to test your retry logic? Start with npx @anonymilyhq/cli listen 3000 to capture webhooks locally and replay them to verify your exponential backoff implementation. For production webhook gateways with SLA guarantees, see Anonymily vs Hookdeck. Learn more at anonymily.com.

Webhook Idempotency: Handling Duplicate Events

Anonymily — Thu, 02 Jul 2026 04:38:48 +0000

The Silent Killer: Why Webhook Idempotency Matters

You deploy a webhook handler that charges a customer $50 on every payment.completed event. The payment provider retries the webhook once due to a temporary network timeout. Your handler processes it twice. Now your customer is charged $100, and you're fielding an angry support ticket.

This is the core problem with webhook idempotency: duplicate events are inevitable. Network failures, timeouts, provider retries, and even your own restarts can cause the same event to be delivered multiple times. Without webhook idempotency duplicate events handling, you risk corrupting data, double-charging users, or creating orphaned records. The solution isn't to prevent duplicates—it's to make your handler idempotent, so processing the same event twice produces the same result as processing it once.

Prerequisites

A webhook provider account (Stripe, GitHub, Shopify, or similar) with webhook delivery logs
Familiarity with HTTP POST requests and JSON payloads
A backend runtime: Node.js, Python, or similar
A database or cache layer (PostgreSQL, Redis) to track processed event IDs
Basic understanding of HTTP status codes and retry semantics

Implementing Idempotent Webhook Handling

Webhook idempotent handling relies on three principles:

Unique event identifiers — every webhook payload includes a stable, unique ID
Deduplication storage — track which event IDs you've already processed
Idempotent operations — structure your business logic so re-execution is safe

Step 1: Extract and Validate the Event ID

Every webhook provider includes a unique event identifier in the payload. Stripe uses id, GitHub uses delivery, Shopify uses X-Shopify-Webhook-Id. Always extract this first.

// Express.js example
const express = require('express');
const app = express();

app.post('/webhook/stripe', express.json(), async (req, res) => {
  // Extract the event ID — this is your deduplication key
  const eventId = req.body.id;

  if (!eventId) {
    return res.status(400).json({ error: 'Missing event ID' });
  }

  console.log(`Processing event: ${eventId}`);

  try {
    // Check if we've already processed this event
    const alreadyProcessed = await checkEventProcessed(eventId);

    if (alreadyProcessed) {
      console.log(`Event ${eventId} already processed, skipping`);
      return res.status(200).json({ status: 'already_processed' });
    }

    // Process the event
    await handleStripeEvent(req.body);

    // Mark as processed
    await markEventProcessed(eventId);

    res.status(200).json({ status: 'processed' });
  } catch (error) {
    console.error(`Error processing event ${eventId}:`, error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Step 2: Store Processed Event IDs

Use a database or cache to track which events you've already handled. For high-volume webhooks, Redis is ideal; for lower volume, a simple database table works.

PostgreSQL approach:

CREATE TABLE webhook_events (
  id SERIAL PRIMARY KEY,
  event_id VARCHAR(255) UNIQUE NOT NULL,
  event_type VARCHAR(100) NOT NULL,
  processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  payload JSONB,
  INDEX idx_event_id (event_id)
);

Redis approach (Node.js):

const redis = require('redis');
const client = redis.createClient();

async function checkEventProcessed(eventId) {
  const key = `webhook:${eventId}`;
  const exists = await client.exists(key);
  return exists === 1;
}

async function markEventProcessed(eventId) {
  const key = `webhook:${eventId}`;
  // Set with 24-hour expiration to avoid unbounded memory growth
  await client.setEx(key, 86400, 'processed');
}

Step 3: Make Your Business Logic Idempotent

Even with deduplication, structure your operations to be idempotent. Avoid operations that fail if repeated:

Bad (not idempotent):

async function handlePaymentCompleted(event) {
  // This creates a duplicate charge if called twice
  const charge = await stripe.charges.create({
    amount: event.data.amount,
    currency: event.data.currency,
  });

  await db.orders.update(event.data.order_id, {
    status: 'paid',
    charge_id: charge.id,
  });
}

Good (idempotent):

async function handlePaymentCompleted(event) {
  const orderId = event.data.order_id;

  // Check if order is already marked as paid
  const order = await db.orders.findById(orderId);
  if (order.status === 'paid') {
    console.log(`Order ${orderId} already paid, skipping charge`);
    return;
  }

  // Use idempotency keys if the provider supports them
  const charge = await stripe.charges.create(
    {
      amount: event.data.amount,
      currency: event.data.currency,
    },
    {
      idempotencyKey: `order-${orderId}-${event.data.created}`,
    }
  );

  await db.orders.update(orderId, {
    status: 'paid',
    charge_id: charge.id,
  });
}

Step 4: Return 200 Immediately, Process Asynchronously

Always return HTTP 200 to the webhook provider before your business logic completes. This prevents provider retries while you're still processing:

app.post('/webhook/stripe', express.json(), async (req, res) => {
  const eventId = req.body.id;

  // Return 200 immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  setImmediate(async () => {
    try {
      const alreadyProcessed = await checkEventProcessed(eventId);
      if (!alreadyProcessed) {
        await handleStripeEvent(req.body);
        await markEventProcessed(eventId);
      }
    } catch (error) {
      console.error(`Async error processing ${eventId}:`, error);
      // Log to monitoring system for manual review
    }
  });
});

Common Errors and Fixes

Error 1: "Duplicate Key Violation" in Your Event Table

Error message:

ERROR: duplicate key value violates unique constraint "webhook_events_event_id_key"

Root cause: A race condition where two requests for the same event ID hit your database simultaneously, both pass the deduplication check, and both try to insert.

Fix: Use database-level locking or atomic operations:

// PostgreSQL with advisory lock
async function processWebhookAtomic(eventId, handler) {
  const lockId = hashEventId(eventId); // Convert to numeric hash

  const client = await db.connect();
  try {
    await client.query('SELECT pg_advisory_lock($1)', [lockId]);

    const alreadyProcessed = await client.query(
      'SELECT 1 FROM webhook_events WHERE event_id = $1',
      [eventId]
    );

    if (alreadyProcessed.rows.length > 0) {
      return { status: 'already_processed' };
    }

    await handler();

    await client.query(
      'INSERT INTO webhook_events (event_id, processed_at) VALUES ($1, NOW())',
      [eventId]
    );

    return { status: 'processed' };
  } finally {
    await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
    client.release();
  }
}

Error 2: "Event Processed Twice" Despite Deduplication

Symptom: You see duplicate charges or records even with deduplication in place.

Root cause: Your deduplication check happens after you've already made an external API call, or you're not using the event ID correctly.

Fix: Check deduplication before any side effects:

// WRONG: Check happens after Stripe call
const charge = await stripe.charges.create({ ... });
const alreadyProcessed = await checkEventProcessed(eventId);

// CORRECT: Check first
const alreadyProcessed = await checkEventProcessed(eventId);
if (alreadyProcessed) return;
const charge = await stripe.charges.create({ ... });

Also verify you're extracting the event ID correctly for your provider:

// Stripe: event.id
// GitHub: headers['x-github-delivery']
// Shopify: headers['x-shopify-webhook-id']
const eventId = req.body.id || req.headers['x-github-delivery'];

Frequently Asked Questions

Q: How long should I store processed event IDs?

A: At minimum, store them for the provider's maximum retry window (typically 24–72 hours). For audit purposes, keep them longer. Redis with 30-day expiration is reasonable; database retention depends on your compliance requirements. Stripe events are immutable and include a timestamp, so you can safely delete old records after 90 days.

Q: What if my database is down when a webhook arrives?

A: Return 5xx status immediately so the provider retries. Use a local queue (file, in-memory buffer, or local SQLite) as a fallback to capture the event, then process it when the database recovers. For development and testing, Anonymily's webhook inspector captures webhooks in the cloud even when localhost is down, letting you replay them once your handler is ready.

Q: Can I use just timestamps instead of event IDs for deduplication?

A: No. Multiple events can have the same timestamp (millisecond precision), and timestamps don't guarantee uniqueness across retries. Always use the provider's event ID. If a provider doesn't include one, generate a hash of the payload content, but this is fragile if the provider modifies the payload between retries.

Testing Your Idempotency

During local development, test duplicate delivery manually. Use Test Webhooks Locally Without ngrok to capture real webhook payloads, then replay them to verify your handler processes them only once.

Start by running npx @anonymilyhq/cli listen 3000 to get a stable endpoint URL. Trigger the same webhook twice from your provider's dashboard, and confirm your deduplication logic prevents double-processing. For Stripe, GitHub, or Shopify testing, the Pro tier offers provider-signed synthetic events so you can test without manual triggers.

Webhook idempotency isn't optional—it's the difference between a reliable integration and a production incident. Build it in from the start.

How to Test Shopify Webhooks Locally

Anonymily — Fri, 26 Jun 2026 05:38:13 +0000

The Problem: Shopify Webhooks Won't Hit Your Local Machine

You're building a Shopify app. Your backend listens on http://localhost:3000/webhooks/orders, but when you trigger an order in your test store, nothing arrives. Shopify can't reach your machine—it sits behind a NAT, firewall, or corporate proxy. You need to test Shopify webhooks locally, but setting up ngrok, exposing secrets, or deploying to staging every time you change webhook logic is friction you don't need.

This guide walks you through three concrete approaches to test Shopify webhooks locally, from quick manual testing to production-grade inspection.

Prerequisites

A Shopify Partner account and a development store (free tier works)
Node.js 16+ installed locally
A webhook handler running on localhost:3000 (Express, Fastify, or similar)
Familiarity with Shopify Admin API and webhook subscriptions
curl or Postman for manual testing

Testing Shopify Webhooks Locally: Three Approaches

Approach 1: Manual Testing with Curl (Fastest for Iteration)

Before you wire up a tunnel or relay, manually send a Shopify order webhook payload to your handler. This lets you verify signature validation and payload parsing without waiting for a real order event.

First, grab a real Shopify webhook payload structure. Create a JSON file matching the Shopify order webhook schema:

{
  "id": 1234567890,
  "email": "test@example.com",
  "created_at": "2024-01-15T10:30:00-05:00",
  "updated_at": "2024-01-15T10:30:00-05:00",
  "number": 1001,
  "user_id": null,
  "billing_address": {
    "first_name": "Test",
    "last_name": "Customer",
    "phone": "5551234567",
    "company": null,
    "address1": "123 Main St",
    "address2": null,
    "city": "Springfield",
    "province": "IL",
    "country": "United States",
    "zip": "62701",
    "province_code": "IL",
    "country_code": "US"
  },
  "line_items": [
    {
      "id": 1,
      "variant_id": 1,
      "title": "Test Product",
      "quantity": 1,
      "sku": "TEST-001",
      "variant_title": null,
      "vendor": "Test Vendor",
      "fulfillment_service": "manual",
      "product_id": 1,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "price": "99.99",
      "total_discount": "0.00"
    }
  ],
  "total_price": "99.99",
  "total_tax": "0.00",
  "currency": "USD",
  "financial_status": "paid",
  "fulfillment_status": null,
  "tags": "test"
}

Save this as order-webhook.json. Now, start your local webhook handler:

node server.js
# Output: Listening on http://localhost:3000

Send the payload via curl:

curl -X POST http://localhost:3000/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Hmac-SHA256: dummy-signature" \
  -d @order-webhook.json

Your handler receives the payload. If you're validating HMAC signatures (which you should), you'll need to skip verification during manual testing or use a test signature. Most Shopify webhook handlers check an environment variable:

const crypto = require('crypto');

function verifyShopifyWebhook(req, secret) {
  if (process.env.SKIP_WEBHOOK_VERIFICATION === 'true') {
    return true; // Only in local dev
  }

  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = req.rawBody; // Store raw body before JSON parsing
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  return hash === hmac;
}

Set SKIP_WEBHOOK_VERIFICATION=true locally, then test again. You'll see logs from your handler confirming the payload arrived.

Limitation: This approach doesn't test real Shopify signatures or timing. Use it only for rapid iteration on handler logic.

Approach 2: Tunnel-Based Testing (ngrok or Similar)

For real webhook events from Shopify, expose your local server to the internet via a tunnel. ngrok is the most common choice:

ngrok http 3000

ngrok outputs a public URL like https://abc123.ngrok.io. In your Shopify app settings, register your webhook endpoint as https://abc123.ngrok.io/webhooks/orders.

Now when you create an order in your test store, Shopify sends a real webhook with a valid HMAC signature. Your handler receives it, validates the signature, and processes the order.

Trade-offs:

✅ Real Shopify signatures and timing
❌ URL changes every restart (unless you pay for a static domain)
❌ Secrets exposed in terminal history
❌ Adds latency; harder to debug network issues

Compare tunnel approaches in detail.

Approach 3: Webhook Relay with Stable Endpoints (Recommended for Debugging)

A webhook relay sits between Shopify and your localhost, capturing events in the cloud and forwarding them to your machine over a persistent connection. This survives restarts and lets you inspect, replay, and modify payloads.

Start your local handler:

node server.js

In another terminal, start the relay:

npx @anonymilyhq/cli listen 3000

The CLI outputs a stable endpoint URL:

✓ Listening on http://localhost:3000
✓ Webhook endpoint: https://api.anonymily.com/h/my-shopify-app

Register https://api.anonymily.com/h/my-shopify-app in your Shopify webhook settings. When you trigger an order, the relay captures it and forwards it to your local handler over a Server-Sent Events connection. Your handler processes it normally.

The relay also persists the webhook in the cloud (48 hours on the free tier). You can inspect the payload, response, and headers in the web dashboard:

# View all captured webhooks
https://api.anonymily.com/h/my-shopify-app

On the Pro tier, you can modify and replay webhooks with re-signed HMAC, helping you debug edge cases without triggering new orders:

# Replay with modified payload (Pro feature)
# Signature is automatically re-signed

This approach is ideal for Shopify order webhook debugging because:

✅ Stable endpoint (survives restarts and redeploys)
✅ Captures webhooks even when localhost is down
✅ Inspect and replay without new orders
✅ No secrets in terminal
❌ Free tier limited to 200 requests/hook and 48h history

Common Errors and Fixes

Error 1: "Invalid HMAC Signature"

Exact error:

Error: HMAC signature verification failed. Expected: abc123, got: xyz789

Root cause: You're manually testing with curl but your handler validates the HMAC. The X-Shopify-Hmac-SHA256 header you sent doesn't match the body hash.

Fix:

Set SKIP_WEBHOOK_VERIFICATION=true during local manual testing.
For real Shopify events, ensure you're reading the raw request body before JSON parsing. Many frameworks parse JSON first, destroying the raw bytes needed for HMAC validation.

// Express example: capture raw body
const express = require('express');
const app = express();

app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/orders', (req, res) => {
  const rawBody = req.body; // Buffer, not string
  const hmac = req.headers['x-shopify-hmac-sha256'];
  // Now validate HMAC against rawBody
});

Error 2: "Webhook Endpoint Not Reachable"

Exact error (from Shopify Admin):

Webhook delivery failed: Connection refused. The endpoint may be down or unreachable.

Root cause: Your local handler crashed, or the tunnel/relay isn't running.

Fix:

Verify your local handler is running: curl http://localhost:3000/health (if you expose a health check).
If using a tunnel, check that it's still active (ngrok URLs expire after 2 hours of inactivity on free tier).
If using a relay, verify the CLI is still connected: npx @anonymilyhq/cli listen 3000 should show ✓ Connected.
Check Shopify's webhook delivery logs in Admin > Settings > Notifications > Webhooks to see the exact error.

Frequently Asked Questions

Q: Do I need to validate Shopify webhook signatures locally?

A: Yes, in your handler code. Locally, you can skip verification during rapid iteration by checking an environment variable, but always validate in staging and production. Signature validation ensures the webhook came from Shopify, not an attacker.

Q: Can I test Shopify order webhooks without creating real orders?

A: Partially. You can manually send mock payloads via curl to test your handler logic. For real Shopify signatures and timing, you need either a real order (or a test order in your dev store) or a relay that supports provider-signed synthetic events (Anonymily Pro feature).

Q: What's the difference between ngrok and a webhook relay for debugging Shopify webhooks?

A: ngrok exposes your local port directly; the URL changes on restart. A relay captures webhooks in the cloud and forwards them to your machine, surviving restarts and letting you inspect/replay payloads. See a detailed comparison.

Next Steps

Start with manual curl testing to verify your handler logic. Once that works, use a tunnel or relay to receive real Shopify events. For production, always validate HMAC signatures, log webhook deliveries, and implement idempotency (Shopify may retry failed webhooks).

To streamline debugging, try npx @anonymilyhq/cli listen 3000 and register the stable endpoint in Shopify. You'll get webhook inspection and replay without managing tunnels or secrets. Visit anonymily.com to learn more.

How to Test GitHub Webhooks Locally Without Port Forwarding

Anonymily — Wed, 24 Jun 2026 03:54:38 +0000

Testing webhooks locally is one of those problems that sounds simple until you actually try it. Your GitHub webhook needs a publicly routable URL, but your development machine is behind a NAT or firewall. You can't just point GitHub at http://localhost:3000/webhook—GitHub's servers can't reach it.

This article covers the real approaches developers use to test GitHub webhooks locally, their trade-offs, and when to reach for each one.

The Core Problem

GitHub webhooks work by making HTTP POST requests to a URL you specify. That URL must be publicly accessible over the internet. Your local machine typically isn't. You have a few options:

Deploy to staging – reliable but slow feedback loop
Port forward or expose your machine – security risk, fragile
Use a tunneling service – works well, but adds complexity
Use a webhook relay/inspector – captures and forwards events

Let's walk through each approach with real code.

Option 1: ngrok (The Classic)

ngrok creates a tunnel from a public URL to your localhost. It's been the go-to for years.

Setup:

# Install ngrok
brew install ngrok  # macOS
# or download from https://ngrok.com

# Start your Express webhook handler
node webhook-server.js

# In another terminal, expose port 3000
ngrok http 3000

ngrok gives you a URL like https://abc123.ngrok.io. You paste that into GitHub's webhook settings, and requests flow through.

Pros:

Simple, well-documented
Works with any HTTP service
Free tier available
ngrok web UI shows request/response history

Cons:

URL changes on restart (free tier) unless you pay for a static domain
Adds a hop; latency increases slightly
ngrok session dies if your machine sleeps
Free tier has bandwidth limits

Real webhook handler example:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET;

// Middleware to verify GitHub's HMAC signature
function verifyGitHubSignature(req, res, next) {
  const signature = req.headers['x-hub-signature-256'];
  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }

  const body = req.rawBody || JSON.stringify(req.body);
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(body)
    .digest('hex');
  const expected = `sha256=${hash}`;

  if (!crypto.timingSafeEqual(signature, expected)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  next();
}

// Capture raw body for signature verification
app.use(express.raw({ type: 'application/json' }));
app.use((req, res, next) => {
  req.rawBody = req.body;
  req.body = JSON.parse(req.body);
  next();
});

app.post('/webhook', verifyGitHubSignature, (req, res) => {
  const event = req.headers['x-github-event'];
  const payload = req.body;

  console.log(`Received ${event} event`);
  console.log(`Repository: ${payload.repository?.full_name}`);
  console.log(`Action: ${payload.action}`);

  // Handle specific events
  if (event === 'push') {
    console.log(`Pushed ${payload.commits.length} commits to ${payload.ref}`);
  } else if (event === 'pull_request') {
    console.log(`PR ${payload.action}: ${payload.pull_request.title}`);
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Option 2: Cloudflare Tunnel

Cloudflare Tunnel (formerly Argo Tunnel) is similar to ngrok but backed by Cloudflare's infrastructure.

Setup:

brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel --url http://localhost:3000

You get a URL like https://abc123.trycloudflare.me.

Pros:

Free, no bandwidth limits
Stable URLs with a paid Cloudflare domain
Lower latency (Cloudflare edge network)
Works reliably

Cons:

URL changes on restart (free tier)
Requires Cloudflare account
Less webhook-specific tooling than ngrok

Option 3: Webhook Inspector (Anonymily)

Instead of tunneling your entire machine, a webhook inspector captures events in the cloud and forwards them to your localhost over a persistent connection. This is different from tunneling.

How it works:

You get a stable public endpoint: https://api.anonymily.com/h/my-github-hook
You point GitHub at that URL
You run npx @anonymilyhq/cli listen 3000 on your machine
The CLI connects to Anonymily and listens for events
When GitHub posts to the endpoint, Anonymily captures it and forwards it to your localhost over Server-Sent Events
Your handler processes it normally

Setup:

# Terminal 1: Start your webhook handler (same code as above)
node webhook-server.js

# Terminal 2: Start the Anonymily listener
npx @anonymilyhq/cli listen 3000

# Output:
# ✓ Listening on https://api.anonymily.com/h/abc12345
# ✓ Forwarding to http://localhost:3000

Then paste https://api.anonymily.com/h/abc12345 into GitHub's webhook settings.

Pros:

Stable endpoint that survives restarts
Captures events even when localhost is down (replay later)
Web UI shows full request/response history
No port forwarding or machine exposure
Free tier includes 200 requests per hook
Pro tier ($9/month) adds modify-and-replay, signature verification helpers, and provider-signed synthetic test events

Cons:

Adds a dependency (requires Anonymily account)
Not suitable for production (use Hookdeck or Svix for that)
Free tier limited to 48 hours of history

When to use it: You're iterating fast and want a stable endpoint that persists across restarts. You don't want to manage ngrok URLs or Cloudflare tunnels.

Option 4: Local Reverse Proxy (Advanced)

If you control your own domain and have a VPS, you can reverse-proxy requests to your local machine. This is more work but gives you full control.

# On your VPS, in nginx.conf
server {
    listen 443 ssl http2;
    server_name webhook.example.com;

    ssl_certificate /etc/letsencrypt/live/webhook.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/webhook.example.com/privkey.pem;

    location / {
        proxy_pass http://your-home-ip:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Pros:

Full control, no third-party services
Stable domain
Works for any webhook provider

Cons:

Requires a VPS and domain
Security risk if your home IP is exposed
More operational overhead
Not practical for most developers

Comparing the Approaches

Approach	Setup Time	URL Stability	Cost	Best For
ngrok	5 min	Changes on restart	Free/paid	Quick testing, familiar tool
Cloudflare Tunnel	5 min	Free tier unstable	Free/paid	Developers already using Cloudflare
Webhook Inspector	2 min	Stable	Free/paid	Fast iteration, stable endpoints
Reverse Proxy	30 min	Stable	VPS cost	Full control, production-like

Best Practices

Always verify signatures. GitHub signs every webhook with an HMAC. Use the x-hub-signature-256 header to validate authenticity. The code example above shows how.

Log everything during development. Print the event type, payload, and any processing results. You'll debug faster.

Test with real events. Don't mock GitHub's payloads—use actual events from your test repository. Replay features in ngrok and Anonymily are invaluable here.

Handle idempotency. GitHub retries failed webhooks. Your handler should be idempotent (safe to call multiple times with the same data). Use a delivery ID or timestamp to deduplicate.

Set appropriate timeouts. GitHub waits 30 seconds for a response. If your handler takes longer, GitHub times out and retries. Keep webhook handlers fast.

Getting Started

For most developers, start with ngrok or a webhook inspector. ngrok is the most familiar; Anonymily is faster if you want a stable endpoint without managing URLs.

If you want to try a webhook inspector, run:

npx @anonymilyhq/cli listen 3000

Then visit https://anonymily.com to create an endpoint and see the web UI. It takes 30 seconds.

Choose the tool that fits your workflow. The important thing is testing webhooks locally before pushing to production.

Test Webhooks Locally Without ngrok

Anonymily — Tue, 23 Jun 2026 19:14:36 +0000

The ngrok Problem

If you've built against Stripe, GitHub, or Shopify webhooks, you know the friction: spin up ngrok, get a random URL, paste it into your provider's dashboard, wait for events, debug locally, restart ngrok (new URL), repeat. It works, but it's a loop that kills momentum.

The real issue isn't that you need a tunnel—it's that the tunnel is stateless and ephemeral. Every restart breaks the endpoint. Every new session is manual setup. For teams, sharing a tunnel URL adds complexity. And if you're testing signature verification or replay logic, you're stuck with whatever the provider sends, whenever they send it.

Let's look at what actually works to test webhooks locally, and when each approach makes sense.

Option 1: Local HTTP Server + Manual Testing

The simplest approach: run a local server, trigger events by hand, inspect the payload.

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', JSON.stringify(req.body, null, 2));
  console.log('Headers:', req.headers);
  res.status(200).json({ ok: true });
});

app.listen(3000, () => console.log('Listening on :3000'));

Then curl a fake event:

curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"event": "charge.succeeded", "id": "test_123"}'

Pros:

Zero dependencies, full control.
Fast feedback loop.
Easy to modify payloads and test edge cases.

Cons:

You're not testing against real provider signatures.
No way to test retry logic or delivery guarantees.
Doesn't scale to multiple team members or CI/CD.

This is fine for unit-test-level webhook logic, but it's not integration testing.

Option 2: Tunneling (ngrok, Cloudflare Tunnel, Bore)

A tunnel exposes your local server to the internet so providers can reach it.

ngrok:

ngrok http 3000
# Forwarding https://abc123.ngrok.io -> http://localhost:3000

Then register https://abc123.ngrok.io/webhook in your provider's dashboard.

Cloudflare Tunnel:

cloudflared tunnel run --url http://localhost:3000 my-tunnel

Pros:

Works with real providers and real events.
Tests signature verification end-to-end.
Widely known and documented.

Cons:

URL changes on every restart (unless you pay for ngrok Pro).
Manual dashboard updates each time.
Latency and potential rate limits.
Not ideal for team workflows—who owns the tunnel?
No built-in request history or replay.

For one-off testing, it's acceptable. For iterative development, it's tedious.

Option 3: Stable Endpoint + Local Relay

A better approach: get a stable, named endpoint that survives restarts, and relay events to your local machine over a persistent connection.

With Anonymily, you run:

npx @anonymilyhq/cli listen 3000

You get a stable URL like https://api.anonymily.com/h/your-app that doesn't change. The CLI opens a Server-Sent Events connection to Anonymily's cloud, which forwards captured webhooks 1:1 to localhost:3000. If your local server restarts, the relay reconnects automatically.

Pros:

Stable endpoint—register once, forget it.
Survives local restarts and redeploys.
Built-in request history and inspection.
Replay individual events without re-triggering in the provider.
Works offline: captures requests even if localhost is temporarily down.
No ngrok URL juggling.

Cons:

Not a production event gateway (use Hookdeck or Svix for that).
Requires internet connection to the relay service.
Free tier has limits (200 requests per hook, 48 hours history).

For development and testing, this removes the friction ngrok introduces.

Option 4: Docker + Compose for Isolation

If you're testing multiple services or want reproducible environments, use Docker:

version: '3'
services:
  webhook-receiver:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    volumes:
      - .:/app
      - /app/node_modules

Run docker-compose up, then tunnel to localhost:3000 inside the container. This isolates your webhook handler from your host machine and makes CI/CD integration cleaner.

Pros:

Reproducible environment.
Easy to test against different Node versions or dependencies.
Closer to production setup.

Cons:

More overhead than a bare local server.
Debugging requires extra setup (debugger ports, volume mounts).

Option 5: Mock Provider Events in Tests

For unit and integration tests, mock the webhook payload entirely:

const request = require('supertest');
const app = require('./app');

describe('POST /webhook', () => {
  it('should process a charge.succeeded event', async () => {
    const payload = {
      id: 'evt_123',
      type: 'charge.succeeded',
      data: {
        object: {
          id: 'ch_456',
          amount: 2000,
          currency: 'usd'
        }
      }
    };

    const res = await request(app)
      .post('/webhook')
      .set('Content-Type', 'application/json')
      .send(payload);

    expect(res.status).toBe(200);
    expect(res.body.ok).toBe(true);
  });
});

Pros:

Fast, deterministic, no external dependencies.
Easy to test error cases and edge cases.
CI/CD friendly.

Cons:

Doesn't test against real provider signatures or timing.
Requires maintaining mock payloads as provider APIs evolve.

Use mocks for unit tests, and a real endpoint for integration tests.

Signature Verification

Whichever method you choose, verify HMAC signatures locally. Providers (Stripe, GitHub, Shopify) sign requests with a secret. Your handler must validate the signature before processing:

const crypto = require('crypto');

function verifySignature(req, secret) {
  const signature = req.headers['x-webhook-signature'];
  const body = req.rawBody; // Must be raw bytes, not parsed JSON
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

app.post('/webhook', (req, res) => {
  if (!verifySignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process webhook
  res.status(200).json({ ok: true });
});

Note: you need req.rawBody (the raw bytes before JSON parsing). In Express, use express.raw({ type: 'application/json' }) or a custom middleware.

Choosing Your Approach

Local server only: Quick logic checks, no external dependencies. Skip for real provider testing.

Manual curl requests: Same as above, but you control the payload. Good for edge cases.

ngrok or Cloudflare Tunnel: When you need real provider events and don't mind URL churn. Fine for occasional testing.

Stable endpoint + relay: Best for iterative development. Register once, restart freely, inspect history, replay events. Removes the ngrok friction.

Docker: When reproducibility and CI/CD integration matter more than speed.

Mocked events in tests: Always. Unit tests should be fast and deterministic. Use real endpoints only for integration tests.

Most teams use a mix: mocks in CI, a stable local endpoint for dev, and real provider events in staging.

Getting Started

If you want to test webhooks locally without the ngrok restart loop, try a stable endpoint approach. With Anonymily, you can get one in seconds:

npx @anonymilyhq/cli listen 3000

You'll get a stable URL, built-in request history, and replay without re-triggering events. The free tier covers most development workflows.

Head to https://anonymily.com to learn more and sign up.

Mastering Webhook Signature Verification in Local Dev

Anonymily — Tue, 23 Jun 2026 17:19:57 +0000

The 400 Bad Request Ghost

You’ve set up your listener, configured your tunnel, and triggered a test event from Stripe or GitHub. Everything looks perfect, but your console logs a cryptic error: Invalid signature or a blunt 400 Bad Request.

webhook signature verification is the primary security mechanism that ensures a request actually came from the provider and wasn't intercepted or forged. While the concept is simple—hash the payload with a shared secret and compare it to a header—the implementation is where most developers lose hours of productivity.

In this guide, we’ll look at why signature verification fails, how to fix it in your code, and how to improve your local development workflow using tools like Anonymily to stop the "trigger-fail-restart" cycle.

The Core Concept of Webhook Signature Verification

Most modern providers (Stripe, GitHub, Shopify, Slack) use HMAC (Hash-based Message Authentication Code). The process generally follows these steps:

The provider takes the raw JSON body of the request.
They sign it using a secret key only you and the provider know.
They send the signature in a header (e.g., Stripe-Signature or X-Hub-Signature-256).
Your server repeats the process and compares the resulting hashes.

If even one byte is different, the hashes won't match. This is by design, but it’s also why it’s so fragile during development.

The #1 Culprit: The "Raw Body" Mutation

The most common reason for failure in Node.js (Express/Fastify) is body parsing. By the time your webhook handler receives the request, a middleware like app.use(express.json()) has already parsed the body into a JavaScript object.

When you try to verify the signature, you might try to stringify that object back into JSON. This will almost always fail.

// DO NOT DO THIS
const payload = JSON.stringify(req.body);
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);

Why? Because JSON.stringify might change the whitespace, reorder keys, or handle character escaping differently than the original raw string sent by the provider. To fix this, you must capture the raw buffer before it gets parsed.

The Fix for Express

You need to use the verify callback in the JSON parser to attach the raw buffer to the request object:

app.use(express.json({
  verify: (req, res, buf) => {
    if (req.originalUrl.startsWith('/webhooks')) {
      req.rawBody = buf;
    }
  }
}));

// Then in your handler:
const event = stripe.webhooks.constructEvent(req.rawBody, sig, endpointSecret);

The Secret Mismatch and Environment Drift

It sounds obvious, but using the wrong secret is the second most common failure point. There are usually three different types of keys involved in any API integration:

API Keys: Used to make requests to the provider.
Production Webhook Secret: Used for your live endpoint.
Local/Test Webhook Secret: Specifically for your local tunnel or CLI.

If you are using a tool like stripe listen, it generates a unique local webhook secret that is different from the one in your Stripe Dashboard under "Endpoints." If you copy the secret from the dashboard but use a local tunnel, verification will fail every time.

Timing Attacks and Replay Protection

Providers like Stripe and Shopify include a timestamp in the signature header (e.g., t=1672531200,v1=...). This is to prevent "replay attacks," where a malicious actor intercepts a valid request and sends it again.

If your local machine's clock is significantly out of sync with the provider's servers (clock skew), the verification library will reject the request even if the signature is mathematically correct. This often happens if you've put your laptop to sleep and the system clock hasn't updated properly.

The Developer Workflow Problem

Even with the code fixed, debugging webhooks is painful. Most developers use a tunnel that gives them a random URL. Every time you restart the tunnel, you have to:

Copy the new URL.
Go to the Stripe/GitHub dashboard.
Update the webhook settings.
Trigger a new event.

Across a week of iterating, that copy-paste loop adds up to real lost time. Furthermore, if your local server is down when the webhook hits, that event is lost unless you manually trigger it again from the provider's UI.

Where a tool like Anonymily helps

Anonymily is a developer webhook inspector and local relayer designed to solve these specific frustrations. Instead of a random ephemeral URL, it provides a stable named endpoint that survives restarts and redeploys.

To start receiving webhooks locally, you just run:

npx @anonymilyhq/cli listen 3000

This command does two things: it captures webhooks in the cloud and forwards them 1:1 to your localhost over Server-Sent Events (SSE).

Why this helps with signature verification:

Capture even when offline: Anonymily captures requests even when your localhost is down. You can see exactly what the provider sent, including headers and the raw body.
One-Click Replay: If your signature verification fails, you don't need to trigger a new event from the provider. You can replay the captured request from the Anonymily dashboard. On the Pro plan, you can even edit the body or headers and re-sign the request to test different edge cases.
Synthetic Events: Testing specific scenarios (like a subscription.deleted event) can be hard to trigger manually. Anonymily Pro can generate provider-signed synthetic events for GitHub, Shopify, Slack, and more, so you can test your logic without touching the provider's dashboard.

Leveraging AI for Webhook Diagnosis

If you debug with an AI editor, Anonymily also ships an MCP (Model Context Protocol) server:

npx @anonymilyhq/mcp-server

If you use an AI-powered editor like Cursor or Claude Code, you can connect this MCP server to let the AI read your incoming webhook payloads, diagnose why a signature might be failing, and even suggest the exact code fix for your specific framework. It turns the "guess and check" process into a conversation.

Honest Framing: When NOT to use Anonymily

It is important to be clear: Anonymily is a development and testing tool. It is optimized for visibility, replaying, and debugging.

If you are looking for a production-grade webhook gateway to handle millions of events with high availability and retries for your live infrastructure, you should look at tools like Hookdeck or Svix. Anonymily is the tool you use on your machine to get the code right before you push to production.

Summary of the Fixes

To ensure your webhook signature verification works every time:

Always use the raw body buffer, never a stringified JSON object.
Check your secrets. Ensure the secret in your .env matches the specific endpoint you are hitting (Local vs. Prod).
Check your clock. Ensure your dev machine is synced via NTP.
Use stable URLs. Stop updating dashboards every time you restart your tunnel.

If you're tired of the manual setup, give Anonymily a try for free. You get one named endpoint and 48 hours of history out of the box.

Try it now:

npx @anonymilyhq/cli listen 3000

Learn more at https://anonymily.com.

DEV Community: Anonymily

How to Test SendGrid Webhooks Locally

The Challenge of Testing SendGrid Webhooks Locally

Prerequisites

Testing SendGrid Event Webhooks Locally: Three Approaches

Approach 1: Manual Tunnel with ngrok (Quick, Temporary)

Approach 2: Stable Local Endpoint with Anonymily (Recommended for Development)

Approach 3: Synthetic Test Events (Pro Feature)

Common Errors and Fixes

Error 1: "Signature mismatch" on Every Event

Error 2: "Endpoint returned 5xx; retrying"

Frequently Asked Questions

Next Steps

How to Test Razorpay Webhooks Locally

The Challenge: Testing Razorpay Webhooks Without Public Infrastructure

Prerequisites

Setting Up Razorpay Webhook Testing Locally

Step 1: Create a Local Webhook Handler

Step 2: Expose Your Localhost to Razorpay Using a Stable Tunnel

Step 3: Register the Webhook Endpoint in Razorpay Dashboard

Step 4: Trigger a Test Payment and Observe the Webhook

Common Errors and Fixes

Error 1: ❌ Signature mismatch

Error 2: ECONNREFUSED: Connection refused (localhost:3000)

Frequently Asked Questions

Next Steps

Webhook 400 Bad Request: Debugging & Fixes

The 400 Bad Request Problem

Prerequisites

Debugging Webhook 400 Bad Request Errors: Step-by-Step

Step 1: Capture the Actual Request

Step 2: Check Content-Type and Raw Body Handling

Step 3: Validate JSON Encoding

Step 4: Verify Signature Headers

Step 5: Check Endpoint Configuration

Common Errors and Fixes

Error 1: "SyntaxError: Unexpected token < in JSON at position 0"

Error 2: "413 Payload Too Large" or "Unexpected end of JSON input"

Frequently Asked Questions

Next Steps

How to Test Twilio Webhooks Locally

The Problem: Twilio Webhooks Won't Hit Your Localhost

Prerequisites

Setting Up and Testing Twilio Webhooks Locally

Step 1: Create a Local Webhook Handler

Step 2: Expose Your Localhost to the Internet

Step 3: Configure Twilio Webhook URLs

Step 4: Test with Real Twilio Events

Step 5: Inspect and Replay Payloads

Common Errors and Fixes

Error 1: "Twilio request signature validation failed"

Error 2: "Cannot read property 'validateRequest' of undefined"

Frequently Asked Questions

Webhook Signature Mismatch: Root Causes & Solutions

The Silent Killer: Why Webhook Signature Mismatch Errors Happen

Prerequisites

Debugging and Fixing Webhook Signature Mismatch Errors

Step 1: Understand Your Provider's Signing Algorithm

Step 2: Capture the Exact Request Body

Step 3: Verify Secret Storage and Encoding

Step 4: Debug with Logging and Replay

Common Errors and Fixes

Error 1: "Signature verification failed" on Every Webhook

Error 2: "Signature Mismatch" in Production, Not Local

Frequently Asked Questions

How to Test Slack Webhooks Locally

The Challenge of Testing Slack Webhooks Locally

Prerequisites

How to Test Slack Webhooks Locally: Step-by-Step

Step 1: Create a Slack App and Configure Event Subscriptions

Step 2: Set Up a Local Express Handler

Step 3: Expose Your Local Server with a Public Endpoint

Step 4: Register the Endpoint with Slack

Step 5: Trigger and Capture Events

Step 6: Test Signature Verification

Common Errors and Fixes

Error 1: "Invalid Signature"

Error 2: "Request timestamp too old"

Frequently Asked Questions

Next Steps

Error 1: `❌ Signature mismatch`

Error 2: `ECONNREFUSED: Connection refused` (localhost:3000)