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:

Generate a sample webhook payload
Sign it with your provided test secret
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

# Run the Express example
cd examples/express
npm install
npm run dev

# Run the Hono example
cd examples/hono
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:

Log into your Hookstack Dashboard
Navigate to the Destinations or Routes section
Find the webhook event you want to replay
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

Use environment variables for configuration:

# .env.local
HOOKSTACK_SIGNING_SECRET=your_test_secret

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

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

Signature Verification Failing Locally

Check that your HOOKSTACK_SIGNING_SECRET matches the one used in the test script
Ensure you’re not modifying the request body before verification
Check the request headers match exactly (case-sensitive)

Testing Different Event Types

You can modify the test script to send different event types:

test/send-webhook.ts

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

Get Started

Essentials

Local Development

Using the Test Scripts

Example Applications

Testing with Real Events

Dashboard Replay

Best Practices

Local Development Setup

Troubleshooting

Next Steps

View Examples

Production Deployment

​Local Development

​Using the Test Scripts

​Example Applications

​Testing with Real Events

​Dashboard Replay

​Best Practices

​Local Development Setup

​Troubleshooting

​Next Steps

View Examples

Production Deployment

Local Development

Using the Test Scripts

Example Applications

Testing with Real Events

Dashboard Replay

Best Practices

Local Development Setup

Troubleshooting

Next Steps