Testing & Simulation

Testing webhooks has traditionally been notoriously difficult—webhooks are asynchronous, originate from external services, and often require complex signature verification. Hookbase makes webhook testing straightforward with built-in simulation tools, replay functionality, and a local development tunnel that brings external webhooks directly to your machine.

Whether you're validating a transform, debugging a failed delivery, or building a new integration, Hookbase provides multiple testing approaches to fit your workflow.

Testing Approaches

Hookbase offers several testing methods, each suited for different scenarios:

Method	Best For	Tools
Dashboard	Quick manual testing	Built-in test sender
API	Automated testing	curl, scripts
CLI	Local development	hookbase commands
Provider Tools	End-to-end testing	GitHub/Stripe test events

Choose the approach that fits your needs—or combine them for comprehensive testing coverage.

Simulating Events

From the Dashboard

The dashboard provides a visual testing interface:

1. Navigate to Testing in the sidebar
2. Select a source from the dropdown
3. Enter your test payload in the JSON editor
4. Click Send Test Event
5. View the created event and delivery attempts in real-time

The dashboard automatically adds appropriate headers and handles signature verification for you.

Using curl

Send test webhooks directly to your ingest URL:

curl -X POST https://api.hookbase.app/ingest/{orgSlug}/{sourceSlug} \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test",
    "data": {
      "id": 1,
      "message": "Hello from test webhook"
    }
  }'

This creates a new event and triggers all matching routes, just like a real webhook from the provider.

Using the CLI

Test destinations directly from the command line:

# Test a specific destination
hookbase destinations test dst_abc123

# Test with custom payload
hookbase destinations test dst_abc123 --payload '{"test": true}'

# Test with payload from file
hookbase destinations test dst_abc123 --payload @payload.json

The CLI provides immediate feedback on delivery success or failure.

With Signature Verification

To test signature verification, manually calculate and include the signature header:

# Calculate HMAC-SHA256 signature
PAYLOAD='{"event":"test","data":{"id":1}}'
SECRET="your_webhook_secret"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

# Send with signature
curl -X POST https://api.hookbase.app/ingest/{orgSlug}/{sourceSlug} \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIGNATURE" \
  -d "$PAYLOAD"

This validates that your signature verification configuration is correct.

Replaying Events

Single Event Replay

Replay individual events to reprocess them through your pipeline:

Dashboard

1. Navigate to Events
2. Click on an event to view details
3. Click Replay in the event header
4. Confirm the replay action

API

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/deliveries/{deliveryId}/replay \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

CLI

hookbase deliveries replay del_abc123

WARNING

Replay creates new delivery attempts. The original delivery record is preserved, and a new delivery attempt is created with the current route configuration.

Bulk Replay

Replay multiple deliveries at once, useful for recovering from outages:

Dashboard Bulk Action

1. Navigate to Deliveries
2. Filter by status (e.g., failed)
3. Select deliveries using checkboxes
4. Click Actions → Replay Selected

API with Filters

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/deliveries/bulk-replay \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "status": "failed",
      "startDate": "2026-02-01T00:00:00Z",
      "endDate": "2026-02-11T23:59:59Z"
    }
  }'

CLI

# Replay all failed deliveries
hookbase deliveries bulk-replay --status failed

# Replay with time range
hookbase deliveries bulk-replay --status failed --start 2026-02-01 --end 2026-02-11

# Replay specific source
hookbase deliveries bulk-replay --source src_abc123 --status failed

TIP

Use bulk replay during development to reprocess events after updating transforms or destination configurations.

Testing Transforms

Test JSONata transforms before applying them to production routes:

Dashboard Transform Editor

The transform editor includes a live preview:

1. Navigate to Transforms → Create Transform (or edit existing)
2. Enter your JSONata expression in the editor
3. Paste a sample payload in the Test Payload section
4. Click Test Transform
5. View the transformed output in the Result panel

The preview updates in real-time as you edit the expression.

API Transform Test

Test transforms programmatically:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/transforms/test \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "${ $.user.email }",
    "payload": {
      "user": {
        "email": "[email protected]",
        "name": "Test User"
      }
    }
  }'

Response:

{
  "result": "[email protected]",
  "success": true
}

Example Transform Test

Input Payload:

{
  "event": "order.created",
  "order": {
    "id": "ord_123",
    "items": [
      {"sku": "WIDGET-1", "quantity": 2, "price": 19.99},
      {"sku": "GADGET-5", "quantity": 1, "price": 49.99}
    ],
    "customer": {
      "email": "[email protected]"
    }
  }
}

Transform:

{
  "orderId": $.order.id,
  "customerEmail": $.order.customer.email,
  "totalItems": $sum($.order.items.quantity),
  "totalValue": $sum($.order.items.(quantity * price)),
  "event": "new_order"
}

Output:

{
  "orderId": "ord_123",
  "customerEmail": "[email protected]",
  "totalItems": 3,
  "totalValue": 89.97,
  "event": "new_order"
}

Testing Filters

Validate filter expressions before deploying them:

Dashboard Filter Tester

1. Navigate to Filters → Create Filter (or edit existing)
2. Enter your filter expression
3. Paste a sample payload in the Test Payload section
4. Click Test Filter
5. View whether the filter matches (true/false) and any error messages

API Filter Test

Test filter expressions via API:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/filters/test \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "$.event = \"user.created\" and $.data.email_verified = true",
    "payload": {
      "event": "user.created",
      "data": {
        "user_id": "usr_123",
        "email": "[email protected]",
        "email_verified": true
      }
    }
  }'

Response:

{
  "matches": true,
  "success": true
}

Example Filter Test

Test Case 1: Match

{
  "expression": "$.amount > 100 and $.currency = 'USD'",
  "payload": {
    "amount": 150,
    "currency": "USD",
    "description": "Payment"
  }
}
// Result: matches = true

Test Case 2: No Match

{
  "expression": "$.amount > 100 and $.currency = 'USD'",
  "payload": {
    "amount": 50,
    "currency": "USD",
    "description": "Payment"
  }
}
// Result: matches = false

TIP

Test filters with both matching and non-matching payloads to ensure they behave as expected in all scenarios.

Local Development with Tunnels

Hookbase tunnels bring external webhooks directly to your local development server:

# Start your local server
npm run dev  # Runs on localhost:3000

# Start Hookbase tunnel
hookbase tunnels start 3000

# Tunnel is now live at:
# https://tunnel-abc123.hookbase.app → localhost:3000

# Configure webhook source to use tunnel URL
# OR use CLI to route specific source to tunnel:
hookbase tunnels route src_abc123 --tunnel tun_abc123

# Send test webhook
curl -X POST https://api.hookbase.app/ingest/{orgSlug}/{sourceSlug} \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"id": 1}}'

# Watch it arrive locally in your terminal

Tunnel Monitor TUI

The CLI provides a terminal UI for debugging tunneled webhooks:

# Start tunnel with monitor
hookbase tunnels start 3000 --monitor

# Or open monitor for running tunnel
hookbase tunnels monitor tun_abc123

The monitor displays:

• Real-time webhook events
• Request headers and payload
• Response status and timing
• Error messages if delivery fails

Press q to quit the monitor.

TIP

Tunnels are perfect for testing integrations during development without deploying changes or using tools like ngrok.

CI/CD Testing Patterns

Integrate webhook testing into your CI/CD pipeline:

GitHub Actions Example

name: Test Webhooks
on: [push, pull_request]

jobs:
  test-webhooks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Hookbase CLI
        run: |
          npm install -g @hookbase/cli
          hookbase auth login --api-key ${{ secrets.HOOKBASE_API_KEY }}

      - name: Create Test Source
        run: |
          SOURCE_ID=$(hookbase sources create \
            --name "CI Test Source" \
            --slug ci-test-${{ github.run_id }} \
            --type custom \
            --json | jq -r '.id')
          echo "SOURCE_ID=$SOURCE_ID" >> $GITHUB_ENV

      - name: Create Test Destination
        run: |
          DEST_ID=$(hookbase destinations create \
            --name "CI Test Destination" \
            --url https://webhook.site/${{ secrets.WEBHOOK_SITE_ID }} \
            --json | jq -r '.id')
          echo "DEST_ID=$DEST_ID" >> $GITHUB_ENV

      - name: Create Test Route
        run: |
          hookbase routes create \
            --name "CI Test Route" \
            --source $SOURCE_ID \
            --destination $DEST_ID

      - name: Send Test Event
        run: |
          curl -X POST https://api.hookbase.app/ingest/${{ secrets.ORG_SLUG }}/ci-test-${{ github.run_id }} \
            -H "Content-Type: application/json" \
            -d '{"test": true, "run_id": "${{ github.run_id }}"}'

      - name: Wait for Delivery
        run: sleep 5

      - name: Verify Delivery
        run: |
          DELIVERIES=$(hookbase deliveries list --source $SOURCE_ID --json)
          SUCCESS_COUNT=$(echo $DELIVERIES | jq '[.[] | select(.status == "success")] | length')
          if [ "$SUCCESS_COUNT" -lt 1 ]; then
            echo "No successful deliveries found"
            exit 1
          fi

      - name: Cleanup
        if: always()
        run: |
          hookbase sources delete $SOURCE_ID --force
          hookbase destinations delete $DEST_ID --force

Environment Variables for CI

Store these secrets in your CI environment:

• HOOKBASE_API_KEY - API key for authentication
• ORG_SLUG - Your organization slug
• WEBHOOK_SITE_ID - Test endpoint ID (e.g., webhook.site)

Cleanup After Tests

Always clean up test resources to avoid clutter:

# Delete by ID
hookbase sources delete src_test123 --force
hookbase destinations delete dst_test123 --force

# Delete by name pattern
hookbase sources list --json | \
  jq -r '.[] | select(.name | startswith("CI Test")) | .id' | \
  xargs -I {} hookbase sources delete {} --force

WARNING

Use --force flag in CI to skip confirmation prompts. Be careful not to delete production resources.

Provider Test Events

Most webhook providers offer test event functionality:

Provider	How to Trigger Test Events
GitHub	Repository Settings → Webhooks → Edit webhook → Recent Deliveries → Redeliver
Stripe	Dashboard → Developers → Webhooks → Select endpoint → Send test webhook
Shopify	Settings → Notifications → Webhooks → Select webhook → Send test notification
Slack	App Settings → Event Subscriptions → Retry for failed event
Twilio	Console → Webhooks → Test webhook with sample payload

TIP

Use provider test events for final end-to-end validation after setting up your webhook pipeline in Hookbase.

Best Practices

Testing Checklist

Before deploying webhook configurations to production:

• [ ] Test transforms with representative payloads
• [ ] Verify filter expressions with edge cases
• [ ] Validate signature verification with real signatures
• [ ] Test error scenarios (invalid payloads, timeouts)
• [ ] Replay failed deliveries to ensure idempotency
• [ ] Use tunnels to test locally before deploying
• [ ] Set up monitoring and alerts for delivery failures

Common Testing Scenarios

Scenario 1: New Integration

1. Create source and destination in test environment
2. Use CLI tunnel to route to local server
3. Send test event from provider
4. Validate payload structure
5. Build and test transform
6. Deploy to production

Scenario 2: Transform Update

1. Create new transform version
2. Test with recent production events
3. Apply to test route
4. Replay recent events through test route
5. Compare outputs
6. Update production route

Scenario 3: Debugging Failed Deliveries

1. Filter deliveries by failed status
2. Inspect error messages and response codes
3. Replay single delivery to reproduce
4. Fix destination configuration or transform
5. Bulk replay failed deliveries
6. Monitor success rate

TIP

Keep a collection of sample payloads from each provider for quick testing. Save them in your repository or use Hookbase's saved test payloads feature.