How to Test Webhooks Locally: Modern Workflows Without Security Risks

Testing webhooks during local software development has historically presented a dilemma: expose your local workstation to the public internet using reverse tunnels, or build complex mock servers that often drift from third-party provider behavior. Industry surveys indicate that over 64% of developers experience frequent reconnection drops, DNS caching delays, or accidental port exposure when relying on public tunneling utilities.

A cleaner, modern workflow separates request ingestion from local execution. By capturing incoming webhooks at an ephemeral cloud inspection endpoint like Probe, you can inspect headers and raw payloads in real time, then replay identical requests against your local server safely.

Comparing Local Webhook Testing Approaches

Developers typically choose between three main architectures for local webhook testing: reverse tunnels, cloud inspection endpoints, and static mock generators.

Step-by-Step Workflow: The Ingest-Inspect-Replay Pattern

A repeatable local testing workflow should be fast, deterministic, and isolated. Follow this 4-step framework:

1. Create a Dedicated Ingestion Endpoint

Generate a private endpoint URL in Probe. Each endpoint receives a unique URL (such as https://probe.monobase.io.vn/hooks/ep_github_sync). Provide this URL to your external service (GitHub, Stripe, Shopify, or Slack).

2. Trigger External Webhook Events

Trigger an event from the provider's developer console or test dashboard (e.g. creating a GitHub pull request or initiating a checkout session). The provider sends the HTTP request directly to your Probe endpoint over TLS 1.3.

3. Inspect the Full HTTP Telemetry

In your Probe dashboard, examine the captured request in real time:

• HTTP Method & Path: Confirm the route requested by the provider.
• Headers: Inspect Content-Type, user-agent, and signature tokens (e.g. X-Hub-Signature-256).
• Query Parameters: Verify any query tokens or routing flags appended to the URL.
• Raw Body: Review the unmodified payload formatted with syntax highlighting.

4. Replay Against Your Local Server

Once you understand the event structure, replay the request directly against your local application server using curl:

# Replay captured webhook against your local development server
curl -i -X POST "http://localhost:3000/api/webhooks/github" \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: pull_request" \
  -H "X-Hub-Signature-256: sha256=d5798d249f872f23..." \
  --data-binary '{
    "action": "opened",
    "number": 42,
    "pull_request": {
      "id": 10842,
      "title": "feat: add webhook retry logic",
      "user": { "login": "octocat" }
    }
  }'

Moving from Local Testing to Automated Integration Tests

Manual testing is helpful for initial integration, but automated tests guarantee long-term regression safety. Convert your captured webhook payloads into test fixtures:

// test/webhooks/github.test.ts
import { describe, it, expect } from 'vitest';
import { handleGitHubWebhook } from '@/server/webhooks/github';
import fixturePullRequestOpened from './fixtures/pull_request_opened.json';

describe('GitHub Webhook Handler', () => {
  it('correctly processes pull_request opened events', async () => {
    const rawPayload = JSON.stringify(fixturePullRequestOpened);
    const mockSignature = generateTestSignature(rawPayload, 'test_secret');

    const request = new Request('http://localhost:3000/api/webhooks/github', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-GitHub-Event': 'pull_request',
        'X-Hub-Signature-256': mockSignature,
      },
      body: rawPayload,
    });

    const response = await handleGitHubWebhook(request);
    expect(response.status).toBe(200);

    const body = await response.json();
    expect(body.processed).toBe(true);
    expect(body.pullRequestId).toBe(10842);
  });
});

Security Best Practices for Local Webhook Testing

1. Redact Sensitive Customer Data: Never commit real customer payment records, email addresses, or access tokens into git repositories as test fixtures.
2. Rotate Test Signing Secrets: Use dedicated test signing secrets for local development that are distinct from staging or production secrets.
3. Avoid Unauthenticated Tunnels in Production: Tunnels that expose internal local ports can inadvertently expose internal database administration tools or debug endpoints to the public web.
4. Enforce Ephemeral Data Retention: When using inspection tools, select platforms that automatically expire and purge captured payloads according to your data retention policies.

Frequently Asked Questions