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

# Quickstart

> Get started with Hookstack in under 5 minutes

## Installation

Install Hookstack SDK in your project:

```bash
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:

```bash
# .env
HOOKSTACK_SIGNING_SECRET=your_signing_secret_here
```

### 2. Create Your First Webhook Handler

<AccordionGroup>
  <Accordion icon="nextjs" title="Next.js Route Handler">
    ```typescript
    // 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 }
        );
      }
    }
    ```
  </Accordion>

  <Accordion icon="node" title="Express Handler">
    ```typescript
    // 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;
    ```
  </Accordion>

  <Accordion icon="bolt" title="Hono Handler">
    ```typescript
    // 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;
    ```
  </Accordion>
</AccordionGroup>

### 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:

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

## Security Features

Hookstack provides robust security features out of the box:

<CardGroup cols={2}>
  <Card title="Signature Verification" icon="shield-check">
    Cryptographic verification of webhook signatures using HMAC-SHA256
  </Card>

  <Card title="Timestamp Validation" icon="clock">
    Protection against replay attacks with timestamp verification
  </Card>

  <Card title="Version Control" icon="code-branch">
    Support for multiple signature versions for seamless upgrades
  </Card>

  <Card title="Raw Body Handling" icon="file-code">
    Proper handling of raw request bodies for signature verification
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Security Guide" icon="shield" href="/security">
    Learn about our security features and best practices
  </Card>

  <Card title="Advanced Usage" icon="code" href="/advanced/middleware">
    Custom handlers, middleware, and error handling
  </Card>

  <Card title="TypeScript Guide" icon="typescript" href="/typescript">
    Type definitions and payload interfaces
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/best-practices">
    Production deployment and monitoring
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="bug" title="Signature Verification Failed">
    Common causes of signature verification failures:

    1. Incorrect `HOOKSTACK_SIGNING_SECRET`
    2. Modified request body (ensure raw body parsing)
    3. Missing or incorrect headers
    4. Clock drift between servers (check timestamp)
  </Accordion>

  <Accordion icon="code" title="Express Body Parsing">
    For Express applications, ensure you use `express.raw()` middleware:

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

    Using `express.json()` will modify the request body and break signature verification.
  </Accordion>

  <Accordion icon="clock" title="Handling Long Operations">
    For time-intensive processing:

    ```typescript
    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
    }
    ```

    <Tip>
      The [Next.JS example](https://github.com/dugjason/hookstack-sdk/examples/next-app/src/app/api/webhooks/route.ts) provides a nice example of how to handle this when deploying to Vercel, using the [`waitUntil()`](https://vercel.com/docs/functions/vercel-functions-package#waituntil) async processing function.
    </Tip>
  </Accordion>
</AccordionGroup>