npm package: @hooktraps/webhook-sdk
Description: SDK for pulling webhooks from HookTraps service to your local development environment
Author: HookTraps
Latest version: 1.0.11

# HookTraps Webhook SDK

Pull webhooks from your HookTraps traps to your local development environment.

## Installation

```bash
npm install @hooktraps/webhook-sdk
```

## Usage

### 1. Configure your environment

Create a `.env` file in your project:

```env
HOOKTRAPS_API_KEY=trap_your_api_key_here
HOOKTRAPS_LOCAL_URL=http://localhost:3000/webhooks/stripe
HOOKTRAPS_API_BASE=https://www.hooktraps.com
```

### 2. Start polling for webhooks

```bash
npx hooktraps start
```

### 3. Stop the poller

```bash
npx hooktraps stop
```

### 4. Check status

```bash
npx hooktraps status
```

## Configuration Options

### Environment Variables

- `HOOKTRAPS_API_KEY` - Your HookTraps API key (required)
- `HOOKTRAPS_LOCAL_URL` - **Fallback** local webhook endpoint URL (default: http://localhost:3000/webhooks)
- `HOOKTRAPS_API_BASE` - HookTraps API base URL (default: https://www.hooktraps.com)
- `HOOKTRAPS_TRAP_ID` - Specific trap ID to poll (optional)
- `HOOKTRAPS_WEBHOOK_ID` - Specific webhook ID to poll (optional)

> **Note:** Starting in v1.0.5, you can configure each webhook's local endpoint directly in the HookTraps UI. If a webhook has a `local_endpoint` configured, the SDK will use that instead of `HOOKTRAPS_LOCAL_URL`.

### Command Line Options

```bash
npx hooktraps start --help
```

Options:
- `-k, --api-key <key>` - API key for authentication
- `-u, --url <url>` - Local webhook URL
- `-b, --base <base>` - API base URL
- `-i, --interval <seconds>` - Polling interval (default: 2)
- `-l, --limit <number>` - Events per request (default: 25)
- `--trap-id <id>` - Specific trap ID to poll
- `--webhook-id <id>` - Specific webhook ID to poll

## Examples

### Basic usage with environment variables:

```bash
# Set up .env file
echo "HOOKTRAPS_API_KEY=trap_abc123" >> .env
echo "HOOKTRAPS_LOCAL_URL=http://localhost:3000/webhooks/stripe" >> .env

# Start polling
npx hooktraps start
```

### Multi-Webhook Projects (v1.0.5+):

For projects with multiple webhooks (e.g., Stripe + GitHub), configure each webhook's local endpoint in the HookTraps UI instead of using environment variables:

```bash
# In HookTraps UI, set per-webhook:
# Stripe Webhook   → Local Endpoint: http://localhost:3000/webhooks/stripe
# GitHub Webhook   → Local Endpoint: http://localhost:3000/webhooks/github
# Twilio Webhook   → Local Endpoint: http://localhost:3000/webhooks/twilio

# Single SDK instance handles all webhooks!
npx hooktraps start
```

Each webhook automatically routes to its configured endpoint. No need for multiple SDK processes or complex configuration!

### Using command line options:

```bash
npx hooktraps start \
  --api-key=trap_abc123 \
  --url=http://localhost:8000/webhooks/github \
  --interval=5
```

### Framework-specific examples:

#### Express.js
```javascript
app.post('/webhooks/stripe', (req, res) => {
  console.log('Received webhook:', req.body);
  res.send('OK');
});
```

#### Laravel (PHP)
```php
Route::post('/webhooks/stripe', function (Request $request) {
    Log::info('Webhook received', $request->all());
    return response('OK');
});
```

#### Django (Python)
```python
def stripe_webhook(request):
    print("Received webhook:", request.body)
    return HttpResponse('OK')
```

## Webhook Signature Verification

HookTraps re-signs all webhooks with a **Dev Signing Secret** before sending them to your local app. This allows you to verify webhooks in your local environment just like you would in production.

### Setup

1. Get your **Dev Signing Secret** from the HookTraps webhook page
2. Add it to your `.env`:
   ```env
   HOOKTRAPS_SIGNING_SECRET=whsec_YourDevSigningSecretFromHookTraps
   ```

### Framework-Specific Configuration

The Dev Signing Secret from HookTraps must be configured in your local app's webhook verification. The environment variable name depends on what your framework's webhook library expects:

#### Laravel with Stripe
Laravel's Stripe webhook library expects `STRIPE_WEBHOOK_SECRET`:
```env
STRIPE_WEBHOOK_SECRET=whsec_YourDevSigningSecretFromHookTraps
```

#### Laravel with GitHub
Laravel's GitHub webhook library expects `GITHUB_WEBHOOK_SECRET`:
```env
GITHUB_WEBHOOK_SECRET=YourDevSigningSecretFromHookTraps
```

#### Express.js / Node.js / Other Frameworks
Use whatever variable name your webhook verification library expects, or use:
```env
HOOKTRAPS_SIGNING_SECRET=whsec_YourDevSigningSecretFromHookTraps
```

**Important**: You are NOT using your provider's webhook secret here:
- **Provider Secret** (from Stripe/GitHub/etc) → Enter this in HookTraps under "Provider Endpoint Secret" to verify incoming webhooks
- **Dev Signing Secret** (from HookTraps) → Enter this in your local app to verify webhooks forwarded by HookTraps

## How it works

1. **Poll** - The SDK polls your HookTraps API for pending webhook events
2. **Replay** - Found events are replayed to your local webhook endpoint with new signatures
3. **Acknowledge** - Successfully processed events are marked as acknowledged
4. **Retry** - Failed events are retried on the next poll

## Workflow

```
[Third-party Service] → [HookTraps Trap] → [Your Local Environment]
        │                    │                    │
     Webhook              Stores &              Processes
                         Forwards               Webhook
```

## License

MIT