Quickstart

Installation

Install Hookstack SDK in your project:

npm install @hookstack/sdk
# or
yarn add @hookstack/sdk
# or
pnpm add @hookstack/sdk

Quick Setup

1. Configure Environment

First, set up your signing secret. This is used to verify incoming webhooks:

# .env
HOOKSTACK_SIGNING_SECRET=your_signing_secret_here

2. Create Your First Webhook Handler

Next.js Route Handler

// app/api/webhooks/route.ts
import { NextResponse } from 'next/server';
import { verifyWebhookSignature } from '@hookstack/next';

const SIGNING_SECRET = process.env.HOOKSTACK_SIGNING_SECRET!;

export async function POST(request: Request) {
  try {
    const body = await request.json();

    // Get signature details from headers
    const signature = request.headers.get('x-hookstack-signature');
    const timestamp = request.headers.get('x-hookstack-timestamp');
    const version = request.headers.get('x-hookstack-version');

    if (!signature || !timestamp || !version) {
      return NextResponse.json(
        { error: 'Missing signature headers' },
        { status: 400 }
      );
    }

    // Verify the webhook signature
    verifyWebhookSignature({
      payload: body,
      signature,
      timestamp,
      version,
      signingSecret: SIGNING_SECRET,
    });

    // Handle the webhook event
    if (body.type === 'payment.succeeded') {
      const { amount, currency } = body.data;
      // Process the payment success
      // Your business logic here
    }

    return NextResponse.json({ received: true });
  } catch (err) {
    console.error('Webhook error:', err);
    return NextResponse.json(
      { error: 'Webhook signature verification failed' },
      { status: 401 }
    );
  }
}

Express Handler

// webhooks/handler.ts
import express from 'express';
import { verifyWebhookSignature } from '@hookstack/sdk';

const router = express.Router();
const SIGNING_SECRET = process.env.HOOKSTACK_SIGNING_SECRET!;

router.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const signature = req.headers['x-hookstack-signature'];
    const timestamp = req.headers['x-hookstack-timestamp'];
    const version = req.headers['x-hookstack-version'];

    if (!signature || !timestamp || !version) {
      return res.status(400).json({ error: 'Missing signature headers' });
    }

    // Verify the webhook signature
    verifyWebhookSignature({
      payload: req.body,
      signature,
      timestamp,
      version,
      signingSecret: SIGNING_SECRET,
    });

    // Handle the webhook event
    const event = JSON.parse(req.body);
    if (event.type === 'payment.succeeded') {
      const { amount, currency } = event.data;
      // Process the payment success
      // Your business logic here
    }

    res.json({ received: true });
  } catch (err) {
    console.error('Webhook error:', err);
    res.status(401).json({ error: 'Webhook signature verification failed' });
  }
});

export default router;

Hono Handler

// app/webhooks/route.ts
import { Hono } from 'hono';
import { verifyWebhookSignature } from '@hookstack/sdk';

const app = new Hono();
const SIGNING_SECRET = process.env.HOOKSTACK_SIGNING_SECRET!;

app.post('/webhooks', async (c) => {
  try {
    const body = await c.req.json();

    // Get signature details from headers
    const signature = c.req.header('x-hookstack-signature');
    const timestamp = c.req.header('x-hookstack-timestamp');
    const version = c.req.header('x-hookstack-version');

    if (!signature || !timestamp || !version) {
      return c.json(
        { error: 'Missing signature headers' },
        400
      );
    }

    // Verify the webhook signature
    verifyWebhookSignature({
      payload: body,
      signature,
      timestamp,
      version,
      signingSecret: SIGNING_SECRET,
    });

    // Handle the webhook event
    if (body.type === 'payment.succeeded') {
      const { amount, currency } = body.data;
      // Process the payment success
      // Your business logic here
    }

    return c.json({ received: true });
  } catch (err) {
    console.error('Webhook error:', err);
    return c.json(
      { error: 'Webhook signature verification failed' },
      401
    );
  }
});

export default app;

3. Configure Your Webhook URL

Create a new webhook in your Hookstack dashboard and copy the generated Webhook URL. Set up your webhook URL in your provider’s dashboard and ensure you’ve configured the signing secret correctly:

https://hooks.hookstack.dev/v1/in/custom/abc123

Security Features

Hookstack provides robust security features out of the box:

Signature Verification

Cryptographic verification of webhook signatures using HMAC-SHA256

Timestamp Validation

Protection against replay attacks with timestamp verification

Version Control

Support for multiple signature versions for seamless upgrades

Raw Body Handling

Proper handling of raw request bodies for signature verification

Next Steps

Security Guide

Learn about our security features and best practices

Advanced Usage

Custom handlers, middleware, and error handling

TypeScript Guide

Type definitions and payload interfaces

Best Practices

Production deployment and monitoring

Troubleshooting

Signature Verification Failed

Common causes of signature verification failures:

Incorrect HOOKSTACK_SIGNING_SECRET
Modified request body (ensure raw body parsing)
Missing or incorrect headers
Clock drift between servers (check timestamp)

Express Body Parsing

For Express applications, ensure you use express.raw() middleware:

app.use('/webhooks', express.raw({ type: 'application/json' }));

Using express.json() will modify the request body and break signature verification.

Handling Long Operations

For time-intensive processing:

try {
  // 1. Verify signature first
  verifyWebhookSignature({
    payload: req.body,
    signature,
    timestamp,
    version,
    signingSecret: SIGNING_SECRET,
  });

  // 2. Acknowledge receipt quickly
  res.json({ received: true });

  // 3. Process asynchronously
  await processWebhookAsync(req.body);
} catch (err) {
  // Handle errors appropriately
}

The Next.JS example provides a nice example of how to handle this when deploying to Vercel, using the waitUntil() async processing function.

Get Started

Essentials

Installation

Quick Setup

1. Configure Environment

2. Create Your First Webhook Handler

3. Configure Your Webhook URL

Security Features

Signature Verification

Timestamp Validation

Version Control

Raw Body Handling

Next Steps

Security Guide

Advanced Usage

TypeScript Guide

Best Practices

Troubleshooting

​Installation

​Quick Setup

​1. Configure Environment

​2. Create Your First Webhook Handler

​3. Configure Your Webhook URL

​Security Features

Signature Verification

Timestamp Validation

Version Control

Raw Body Handling

​Next Steps

Security Guide

Advanced Usage

TypeScript Guide

Best Practices

​Troubleshooting

Installation

Quick Setup

1. Configure Environment

2. Create Your First Webhook Handler

3. Configure Your Webhook URL

Security Features

Next Steps

Troubleshooting