firecrawl-webhooks-events

# FireCrawl Webhooks & Events

## Overview
Securely handle FireCrawl webhooks with signature validation and replay protection.

## Prerequisites
- FireCrawl webhook secret configured
- HTTPS endpoint accessible from internet
- Understanding of cryptographic signatures
- Redis or database for idempotency (optional)

## Webhook Endpoint Setup

### Express.js
```typescript
import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/firecrawl',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-firecrawl-signature'] as string;
    const timestamp = req.headers['x-firecrawl-timestamp'] as string;

    if (!verifyFireCrawlSignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handleFireCrawlEvent(event);

    res.status(200).json({ received: true });
  }
);
```

## Signature Verification

```typescript
function verifyFireCrawlSignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.FIRECRAWL_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```

## Event Handler Pattern

```typescript
type FireCrawlEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface FireCrawlEvent {
  id: str