Security

Verify webhook authenticity

Verify that every webhook request actually came from Firecrawl by checking its HMAC-SHA256 signature. This stops attackers from spoofing payloads and lets you trust the data before acting on it.

Secret Key

Your webhook secret is available in the Advanced tab of your account settings. Each account has a unique secret used to sign all webhook requests.

Keep your webhook secret secure and never expose it publicly. If you believe your secret has been compromised, regenerate it immediately from your account settings.

Signature Verification

Each webhook request includes an X-Firecrawl-Signature header:

X-Firecrawl-Signature: sha256=abc123def456...

How to Verify

1. Extract the signature from the X-Firecrawl-Signature header
2. Get the raw request body (before parsing)
3. Compute HMAC-SHA256 using your secret key
4. Compare signatures using a timing-safe function

Implementation

Node/Express

import crypto from 'crypto';
import express from 'express';

const app = express();

// Use raw body parser for signature verification
app.use('/webhook/firecrawl', express.raw({ type: 'application/json' }));

app.post('/webhook/firecrawl', (req, res) => {
  const signature = req.get('X-Firecrawl-Signature');
  const webhookSecret = process.env.FIRECRAWL_WEBHOOK_SECRET;
  
  if (!signature || !webhookSecret) {
    return res.status(401).send('Unauthorized');
  }
  
  // Extract hash from signature header
  const [algorithm, hash] = signature.split('=');
  if (algorithm !== 'sha256') {
    return res.status(401).send('Invalid signature algorithm');
  }
  
  // Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');
  
  // Verify signature using timing-safe comparison
  if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
    return res.status(401).send('Invalid signature');
  }
  
  // Parse and process verified webhook
  const event = JSON.parse(req.body);
  console.log('Verified Firecrawl webhook:', event);
  
  res.status(200).send('ok');
});

app.listen(3000, () => console.log('Listening on 3000'));

Best Practices

• Verify every request. Always check the signature before processing a webhook payload. Reject any request that fails verification with a 401 status.
• Use timing-safe comparisons. Standard string comparison can leak timing information. Use crypto.timingSafeEqual() in Node.js or hmac.compare_digest() in Python.
• Serve your endpoint over HTTPS. This ensures webhook payloads are encrypted in transit.