Development

​

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 )

​

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

​

Best Practices

​

Local Development Setup

1. Use environment variables for configuration:

# .env.local
HOOKSTACK_SIGNING_SECRET=your_test_secret

2. 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
  });
}

3. 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

const payload = {
  type: 'payment.succeeded', // Change this to test different events
  data: {
    // Modify this object to match the event type
  }
};

​

Next Steps