​
Local Development

When developing webhook handlers, you may want to test them before deploying to production. Hookstack provides several tools to make local testing easy and reliable.

​
Using the Test Scripts

The Hookstack SDK includes example applications and test scripts to help you get started. These scripts generate properly signed payloads and send them to your local webhook handler. 
# Open the example directory
cd examples/next-app # or examples/express, examples/hono

# Install dependencies
npm install

# Run the test script
npm run test:script
This will:
  1. Generate a sample webhook payload
  2. Sign it with your provided test secret
  3. Send it to your local webhook endpoint (default: http://localhost:3000/api/webhooks )
The test script is particularly useful for initial integration testing as it ensures your signature verification is working correctly.

​
Example Applications

The SDK includes several example applications that demonstrate proper webhook handling: 
# Run the Next.js example
cd examples/next-app
npm install
npm run dev

​
Testing with Real Events

​
Dashboard Replay

Once you’ve received webhooks in production, you can replay them to your development environment:
  1. Log into your Hookstack Dashboard
  2. Navigate to the Destinations or Routes section
  3. Find the webhook event you want to replay
  4. Click the “Replay” icon to have HookStack re-send the event to your development environment
This allows you to:
  • Test your handler with real production data
  • Debug issues with specific webhook payloads
  • Verify your handler works across different event types
Make sure your development environment is accessible from the internet when using the replay feature. Tools like ngrok or cloudflared can help expose your local server.

​
Best Practices

​
Local Development Setup

  1. Use environment variables for configuration:
# .env.local
HOOKSTACK_SIGNING_SECRET=your_test_secret
  1. Set up proper error handling:
try {
  // Your webhook handling code
} catch (error) {
  console.error('Webhook Error:', error);
  // During development, log the full error
  console.debug('Full error details:', {
    headers: request.headers,
    body: request.body,
    error
  });
}
  1. Use TypeScript for better development experience:
import {type WebhookPayloadV1_0, WebhookPayloadSchemaV1_0 } from '@hookstack/core';

// use the built-in schema validator to ensure your event is valid
const safeEvent = WebhookPayloadSchemaV1_0.parse(event);
await handleWebhook(safeEvent);

async function handleWebhook(event: WebhookPayloadV1_0) {
  // Your event handling code with full type safety
}

​
Troubleshooting

​
Next Steps

View Examples

Browse our collection of example applications

Production Deployment

Learn how to deploy your webhook handler to production