webhook verification

import crypto from 'node:crypto'
 
const TOLERANCE_SECONDS = 300
 
// `rawBody` must be the raw string/Buffer, not a parsed object.
// `signatureHeader` is the value of `X-Cwbl-Signature` (or `X-Cwbl-Signature-Rotated`).
function verifyWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((kv) => kv.split('=')),
  )
  const timestamp = Number(parts.t)
  const received = parts.v1
 
  // reject stale deliveries (replay protection)
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) {
    return false
  }
 
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('hex')
 
  const a = Buffer.from(received ?? '', 'utf8')
  const b = Buffer.from(expected, 'utf8')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

import hashlib
import hmac
import time
 
TOLERANCE_SECONDS = 300
 
 
# `raw_body` must be the raw bytes, not a parsed dict.
# `signature_header` is the value of `X-Cwbl-Signature` (or `X-Cwbl-Signature-Rotated`).
def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    try:
        parts = dict(kv.split("=", 1) for kv in signature_header.split(","))
        timestamp = int(parts["t"])
        received = parts["v1"]
    except (KeyError, ValueError):
        return False  # malformed signature header
 
    # reject stale deliveries (replay protection)
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
 
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
 
    return hmac.compare_digest(received, expected)

// Binding the body as a String (not a DTO) hands you the raw payload,
// exactly as received, before Jackson deserializes it.
@PostMapping("/webhooks/crawlbrulee")
public ResponseEntity<Void> handle(
    @RequestBody String rawBody,
    @RequestHeader("X-Cwbl-Signature") String signature) {
  if (!verifyWebhook(rawBody, signature, SECRET)) {
    return ResponseEntity.status(401).build();
  }
  // safe to parse rawBody now
  return ResponseEntity.ok().build();
}

import express from 'express'
 
const app = express()
 
// Scope a raw body parser to the webhook route — `req.body` arrives
// as a Buffer of the exact bytes on the wire.
app.post(
  '/webhooks/crawlbrulee',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8')
    if (!verifyWebhook(rawBody, req.get('X-Cwbl-Signature'), SECRET)) {
      return res.sendStatus(401)
    }
    const event = JSON.parse(rawBody) // safe to parse now
    res.sendStatus(200)
  },
)
 
// Alternative: keep a global express.json() but stash the raw bytes
// with its `verify` hook before parsing discards them.
app.use(
  express.json({
    verify: (req, _res, buf) => {
      req.rawBody = buf // a Buffer of the exact bytes
    },
  }),
)

// app/api/webhooks/crawlbrulee/route.ts — App Router
export async function POST(req: Request) {
  const rawBody = await req.text() // exact bytes, unparsed
  const signature = req.headers.get('x-cwbl-signature') ?? ''
  if (!verifyWebhook(rawBody, signature, SECRET)) {
    return new Response('invalid signature', { status: 401 })
  }
  const event = JSON.parse(rawBody) // safe to parse now
  return new Response(null, { status: 200 })
}

import json
 
from fastapi import FastAPI, Request, Response
 
app = FastAPI()
 
 
@app.post("/webhooks/crawlbrulee")
async def handle(request: Request):
    raw_body = await request.body()  # bytes, before any parsing
    signature = request.headers.get("x-cwbl-signature", "")
    if not verify_webhook(raw_body, signature, SECRET):
        return Response(status_code=401)
    event = json.loads(raw_body)  # safe to parse now
    return Response(status_code=200)

from flask import Flask, request
 
app = Flask(__name__)
 
 
@app.post("/webhooks/crawlbrulee")
def handle():
    raw_body = request.get_data()  # bytes, exactly as received
    signature = request.headers.get("X-Cwbl-Signature", "")
    if not verify_webhook(raw_body, signature, SECRET):
        return "", 401
    event = request.get_json()  # safe to parse now
    return "", 200

import { Crawlbrulee } from '@crawlbrulee/sdk'
 
const client = new Crawlbrulee({ apiKey: process.env.CRAWLBRULEE_API_KEY })
const TOLERANCE_SECONDS = 300
 
// `headers` and `parsedBody` come from your framework; raw bytes are unavailable.
async function handlePing(headers, parsedBody) {
  const sig = headers['x-cwbl-signature'] ?? ''
  const t = Number(sig.split(',')[0]?.split('=')[1])
  if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) {
    return { status: 401 } // stale
  }
 
  const eventId = headers['x-cwbl-event-id']
  if (await alreadyProcessed(eventId)) return { status: 200 } // already handled
 
  // read only the job id — ignore everything else in the payload
  const jobId = parsedBody.data.job_id
  await client.getScrapeResult(jobId) // API token is the trust anchor
 
  await markProcessed(eventId)
  return { status: 200 }
}

import os
import time
 
from crawlbrulee import Crawlbrulee
 
client = Crawlbrulee(api_key=os.environ["CRAWLBRULEE_API_KEY"])
TOLERANCE_SECONDS = 300
 
 
# `headers` and `parsed_body` come from your framework; raw bytes are unavailable.
def handle_ping(headers, parsed_body):
    sig = headers.get("x-cwbl-signature", "")
    try:
        t = int(sig.split(",")[0].split("=")[1])
    except (IndexError, ValueError):
        return 401
    if abs(time.time() - t) > TOLERANCE_SECONDS:
        return 401  # stale
 
    event_id = headers.get("x-cwbl-event-id", "")
    if already_processed(event_id):
        return 200  # already handled
 
    # read only the job id — ignore everything else in the payload
    job_id = parsed_body["data"]["job_id"]
    client.get_scrape_result(job_id)  # API token is the trust anchor
 
    mark_processed(event_id)
    return 200

import { verifyWebhookSignature } from '@crawlbrulee/sdk'
 
const secret = process.env.CRAWLBRULEE_WEBHOOK_SECRET
 
// `payload` must be the raw request body (string or Uint8Array), not a parsed object.
const result = await verifyWebhookSignature({
  payload: rawBody,
  headers: req.headers, // pass the request headers through as-is
  secret,
  toleranceSeconds: 300, // optional; defaults to 300
})
 
if (result.verified) {
  // result.signedWith is 'primary' or 'rotated'
  console.log('verified, signed with', result.signedWith)
} else {
  // result.reason: 'missing_signature' | 'malformed_signature'
  //              | 'timestamp_out_of_tolerance' | 'signature_mismatch'
  console.warn('rejected:', result.reason)
}

import os
 
from crawlbrulee import verify_webhook_signature
 
secret = os.environ["CRAWLBRULEE_WEBHOOK_SECRET"]
 
# `payload` must be the raw request body (str or bytes), not a parsed dict.
result = verify_webhook_signature(
    payload=raw_body,
    headers=dict(request.headers),  # pass the request headers through as-is
    secret=secret,
    tolerance_seconds=300,  # optional; defaults to 300
)
 
if result.verified:
    # result.signed_with is "primary" or "rotated"
    print("verified, signed with", result.signed_with)
else:
    # result.reason: "missing_signature" | "malformed_signature"
    #              | "timestamp_out_of_tolerance" | "signature_mismatch"
    print("rejected:", result.reason)

// `body` is the parsed webhook payload. Verify the signature first.
const result = await client.fetchScrapeResultFromWebhook(body)
// throws on a failed or cancelled job; returns the scrape result otherwise

# `body` is the parsed webhook payload. Verify the signature first.
result = client.fetch_scrape_result_from_webhook(body)
# raises on a failed or cancelled job; returns the scrape result otherwise