Test Your Webhook Routes Without Hitting Production

The Challenge with Testing Webhooks

Testing webhook integrations is notoriously difficult. You have real webhook providers sending real events, and real downstream services that might charge you money, send notifications, or update production data. One wrong configuration during testing could:

• Trigger actual charges in your payment processor
• Send notifications to real customers
• Create duplicate records in your CRM
• Exhaust API rate limits on third-party services

The typical workaround? Set up a completely separate staging environment with different credentials, different webhooks, and different destinations. It works, but it is time-consuming and still does not let you test edge cases like timeouts or error responses.

Introducing Mock Mode

Hookbase now supports Mock Mode for destinations, allowing you to test your entire webhook routing pipeline without hitting real endpoints. Configure exactly what response your destination should return, and Hookbase will use that mock response instead of making an actual HTTP request.

This means you can:

• Test routing logic with realistic webhook payloads
• Simulate error responses (4xx, 5xx) to verify your retry logic
• Add artificial latency to test timeout handling
• Validate that transforms produce the expected output
• Debug filter conditions without side effects

How It Works

When mock mode is enabled on a destination, Hookbase skips the actual HTTP request and returns your configured mock response instead. The delivery is still recorded, transforms still run, and everything behaves exactly as it would in production, except no external call is made.

Enabling Mock Mode

Navigate to /testing in your Hookbase dashboard, or go directly to a destination's settings:

1. Select the destination you want to mock
2. Toggle Enable Mock Mode on
3. Configure your mock response settings
4. Save the destination

The destination's status indicator will show a "Mock" badge so you always know which destinations are in test mode.

Configuration Options

Mock mode gives you full control over the simulated response:

Status Code

Set the HTTP status code that should be returned. Default is 200.

{
  "mockEnabled": true,
  "mockConfig": {
    "statusCode": 200
  }
}

Use different codes to test various scenarios:

| Status Code | Use Case | |-------------|----------| | 200 | Successful delivery | | 201 | Resource created successfully | | 400 | Bad request (test validation errors) | | 401 | Authentication failure | | 404 | Not found | | 429 | Rate limited (test backoff logic) | | 500 | Server error (test retry behavior) | | 502 | Bad gateway | | 503 | Service unavailable (test circuit breaker) |

Response Body

Define the JSON response body your mock should return:

{
  "mockEnabled": true,
  "mockConfig": {
    "statusCode": 200,
    "responseBody": {
      "success": true,
      "id": "mock_12345",
      "message": "Webhook received"
    }
  }
}

This is useful when your downstream logic depends on values from the response, like an ID or confirmation code.

Response Headers

Set custom response headers:

{
  "mockEnabled": true,
  "mockConfig": {
    "statusCode": 200,
    "responseHeaders": {
      "Content-Type": "application/json",
      "X-Request-Id": "mock-request-123",
      "X-RateLimit-Remaining": "95"
    }
  }
}

Response Delay

Simulate network latency by adding a delay in milliseconds:

{
  "mockEnabled": true,
  "mockConfig": {
    "statusCode": 200,
    "delayMs": 2000
  }
}

Use this to test:

• Timeout handling in your routes
• Slow destination behavior
• Queue processing under latency conditions

Practical Testing Scenarios

Scenario 1: Testing Retry Logic

You have configured your route to retry failed deliveries up to 5 times with exponential backoff. Does it actually work? Set up a mock that returns 503:

{
  "mockEnabled": true,
  "mockConfig": {
    "statusCode": 503,
    "responseBody": {
      "error": "Service temporarily unavailable"
    }
  }
}

Send a test webhook and watch the retries in your delivery log. Verify the backoff timing matches your configuration.

Scenario 2: Testing Circuit Breaker

Your route has a circuit breaker that opens after 5 consecutive failures. Validate it trips correctly:

1. Enable mock mode with a 500 status code
2. Send multiple webhooks through the route
3. Verify the circuit breaker opens after the threshold
4. Change the mock to return 200
5. Send a probe request and verify the circuit closes

Scenario 3: Testing Timeout Handling

Your destination has a 5-second timeout configured. Will it properly timeout slow responses?

{
  "mockEnabled": true,
  "mockConfig": {
    "statusCode": 200,
    "delayMs": 10000
  }
}

Send a webhook and verify the delivery fails with a timeout error, not a success.

Scenario 4: Validating Transforms

You have built a complex JSONata transform and want to verify the output is correct before sending to production:

1. Enable mock mode on the destination (any 200 response)
2. Send test webhooks with various payloads
3. Inspect the delivery records to see exactly what would have been sent
4. The "Transformed Payload" field shows your transform output

Scenario 5: Testing Multiple Destinations

Your route fans out to three destinations. You want to test how the system handles partial failures:

• Destination A: Mock returns 200 (success)
• Destination B: Mock returns 500 (failure)
• Destination C: Mock returns 200 (success)

Verify that destinations A and C are marked successful while B retries independently.

API Configuration

You can also configure mock mode programmatically via the API:

Enable Mock Mode

curl -X PATCH "https://api.hookbase.app/api/organizations/{orgId}/destinations/{destId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "mockEnabled": true,
    "mockConfig": {
      "statusCode": 200,
      "responseBody": {"success": true},
      "responseHeaders": {"X-Custom": "header"},
      "delayMs": 500
    }
  }'

Disable Mock Mode

curl -X PATCH "https://api.hookbase.app/api/organizations/{orgId}/destinations/{destId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "mockEnabled": false
  }'

Database Storage

Mock configuration is stored directly on the destination record with two columns:

• mock_enabled (boolean): Whether mock mode is active
• mock_config (JSON): The mock response configuration

This means mock settings persist across sessions and are tied to the specific destination, not global settings.

Best Practices

1. Use Dedicated Test Destinations

Instead of toggling mock mode on production destinations, create dedicated test destinations:

• stripe-webhook-prod - Real endpoint, mock disabled
• stripe-webhook-test - Any URL, mock enabled

Route test traffic to the test destination during development.

2. Reset After Testing

Always disable mock mode when you are done testing. We recommend adding a visual indicator to your dashboard workflow so you do not accidentally leave a production destination mocked.

3. Test the Full Range

Do not just test the happy path. Use mock mode to test:

• Success responses (200, 201)
• Client errors (400, 401, 403, 404)
• Rate limits (429)
• Server errors (500, 502, 503)
• Timeouts (high delay values)

4. Combine with Real Webhooks

Use mock destinations with real webhook sources. This lets you test the full ingestion and routing pipeline with actual provider payloads, just stopping short of the external HTTP call.

5. Document Your Test Scenarios

Keep a list of mock configurations for common test scenarios. When onboarding new team members or debugging issues, you can quickly reproduce specific conditions.

Getting Started

Mock mode is available now on all Hookbase plans.

1. Navigate to /testing in your dashboard
2. Select a destination to configure
3. Enable mock mode and set your response
4. Send test webhooks and verify behavior

Have questions about testing your webhook integrations? Join our Discord community or reach out to [email protected].

---

Mock mode helps you build reliable webhook integrations with confidence. Test everything before it reaches production.