Generic HTTP webhook ingress channel (@flue/http)

[astrobot-houston]

Originally proposed by @revanthpobala in #328. Their description is reproduced verbatim below.

All community-submitted pull requests are automatically converted to issues (bugs) & discussions (feature requests, enhancements) where they can be triaged and prioritized. Once prioritized, a PR implementation is created automatically.

Summary

Proposes a new generic HTTP webhook ingress channel package (@flue/http) to allow receiving and verifying arbitrary third-party webhook payloads within the Flue framework.

Background & Motivation

Currently, Flue provides dedicated, provider-specific webhook ingress channels (such as GitHub, Stripe, Discord, etc.). However, developers often need to integrate other SaaS providers or custom webhooks that are not supported out of the box. Currently, they have to write custom Hono route handlers from scratch and manually wire up streaming limits, text decoding, and cryptographic signature verification.

A generic HTTP webhook channel solves this by providing a standard, reusable, and framework-integrated contract for arbitrary webhook ingestion.

Goals

• Provide a generic, provider-agnostic HTTP webhook ingress channel (@flue/http).
• Support custom request verification (e.g. signature checking, authorization header validation) with raw request headers and raw body bytes.
• Enforce custom size boundaries/streaming limits on request bodies (defaulting to 1 MiB) to protect the agent runtime.
• Automatically parse incoming payloads as JSON if Content-Type: application/json is specified, whilst leaving text or alternative payloads raw for downstream handling.
• Ensure full runtime compatibility with both standard Node.js and Cloudflare Workers (workerd) environments.

Example

import { createHttpChannel } from '@flue/http';

export const httpChannel = createHttpChannel({
  // Custom verification hook
  async verify(headers, body, rawBody) {
    const signature = headers.get('x-custom-signature');
    if (!signature) {
      // Return a custom Response object to override the default 401:
      return Response.json({ error: 'Unauthorized' }, { status: 401 });
    }
    const expected = computeHmac(rawBody);
    return signature === expected;
  },
  // Process the verified webhook delivery
  async webhook({ c, body, rawBody, json }) {
    console.log('Parsed JSON payload:', json);
    return { ok: true };
  },
});

---

Original implementation from #328 by @revanthpobala

[revanthpobala]

To make it easier for the maintainers, the complete implementation is fully written, tested, and passing all checks on the fork branch: revanthpobala:feat/http-webhook-channel.

Feature Motivation & Problem Matrix

Current Limitation	Why This is Needed	What We Solve / How We Resolve It
No generic SaaS webhook ingestion (only dedicated integrations exist like GitHub, Stripe, Discord).	Developers need to integrate custom or unsupported SaaS providers without writing Hono route boilerplates.	Exposes a lightweight, stateless @flue/http package with a customizable validation interface.
Stream consumption conflicts during cryptographic signature validation.	Modern webhooks require raw bytes (HMAC-SHA256) to verify authenticity and prevent request tampering.	Reads the stream exactly once at the entry point, passing the decoded text, raw Uint8Array bytes, and pre-parsed JSON downstream.
Edge isolate DoS vulnerability (buffering oversized payloads).	Strict memory limits in edge isolates (e.g. Cloudflare Workers' 128MB limit) can cause OOM crashes on large payloads.	Implements an early-termination stream chunk reader that cancels the request immediately when the limit is breached.
Static authorization error response (always defaults to 401).	Webhook providers often expect specific JSON formats or custom HTTP statuses (e.g., 400 Bad Request) on failure.	Allows the verify() hook to return a standard Response object to override and customize the rejected handshake.

---

Real-World Example: Clerk Webhooks

Clerk webhooks use Svix signatures, requiring the raw body string and headers (svix-id, svix-timestamp, svix-signature) for verification:

import { createHttpChannel } from '@flue/http';
import { Webhook } from 'svix'; 

export const clerkWebhookChannel = createHttpChannel({
  async verify(headers, body) {
    const svixId = headers.get('svix-id');
    const svixTimestamp = headers.get('svix-timestamp');
    const svixSignature = headers.get('svix-signature');

    if (!svixId || !svixTimestamp || !svixSignature) {
      return Response.json({ error: 'Missing Svix headers' }, { status: 400 });
    }

    const wh = new Webhook(process.env.CLERK_WEBHOOK_SECRET!);
    try {
      // Svix verification requires the raw string body and headers
      wh.verify(body, {
        'svix-id': svixId,
        'svix-timestamp': svixTimestamp,
        'svix-signature': svixSignature,
      });
      return true;
    } catch {
      return false; // Returns standard 401 Unauthorized
    }
  },
  async webhook({ json }) {
    console.log('Verified Clerk Event:', json);
    return { received: true };
  },
});

---

Verification

• Linter & Typecheck: Biome lint and tsc --noEmit pass with 0 errors.
• Node Test Suite: 9 tests covering limits, verification fallbacks, text payloads, and malformed inputs.
• workerd (Cloudflare Workers) Test Suite: 2 tests verifying full edge-runtime compatibility.