> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Development
> Test and develop your webhook handlers locally
## 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.
```bash
# 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:
```bash Next.js
# Run the Next.js example
cd examples/next-app
npm install
npm run dev
```
```bash Express
# Run the Express example
cd examples/express
npm install
npm run dev
```
```bash Hono
# 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:
1. Log into your [Hookstack Dashboard](https://app.hookstack.dev)
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](https://ngrok.com) or [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/) can help expose your local server.
## Best Practices
### Local Development Setup
1. Use environment variables for configuration:
```env
# .env.local
HOOKSTACK_SIGNING_SECRET=your_test_secret
```
2. Set up proper error handling:
```typescript
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:
```typescript
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
1. Check that your `HOOKSTACK_SIGNING_SECRET` matches the one used in the test script
2. Ensure you're not modifying the request body before verification
3. Check the request headers match exactly (case-sensitive)
You can modify the test script to send different event types:
```typescript test/send-webhook.ts
const payload = {
type: 'payment.succeeded', // Change this to test different events
data: {
// Modify this object to match the event type
}
};
```
## Next Steps
Browse our collection of example applications
Learn how to deploy your webhook handler to production