@paykernel/integration-http

@paykernel/integration-http owns the webhook HTTP status table and raw-body orchestration so Hono, Elysia, Express, and Workers cannot drift. It depends only on @paykernel/core and @paykernel/webhooks. It has no framework imports.

Version 0.1.2 — published on npm. Export map: "." only (types + import).

bun add @paykernel/integration-http
# workspace peers: @paykernel/core @paykernel/webhooks

HTTP policy

@paykernel/webhooks never hardcodes status codes. Map WebhookProcessingOutcome with mapInboxOutcome:

import { mapInboxOutcome, retryAfterSeconds } from "@paykernel/integration-http";

const status = mapInboxOutcome(outcome); // default { kind: "provider_redelivery" }
const statusWithWorker = mapInboxOutcome(outcome, { kind: "durable_worker" });

if (status === 503) {
  const seconds = retryAfterSeconds(outcome);
}

InboxHttpAckPolicy is { kind: "provider_redelivery" } | { kind: "durable_worker" }.

Exhaustive on WebhookProcessingOutcome.outcome:

Default provider_redelivery never ACKs 200 for scheduled_for_retry. durable_worker ACKs 200 only for persisted deferrals (parked / handler_retry). not_available and already_processing stay 503 in both policies.

retryAfterSeconds reads retryAfterMs only on already_processing and scheduled_for_retry. It returns ceil(ms / 1000), at least 1, or undefined if retryAfterMs is absent. processWebhookHttp sets Retry-After only when the mapped status is 503 and seconds are defined.

processWebhookHttp

import { createPaymentClient, stripeGateway } from "@paykernel/core";
import { createWebhookInboxEngine } from "@paykernel/webhooks";
import type { WebhookInboxStore } from "@paykernel/webhooks";
import {
  processWebhookHttp,
  webhookHttpResultToResponse,
} from "@paykernel/integration-http";

declare const store: WebhookInboxStore; // from a @paykernel/store-* adapter after explicit migrate

type Order = { orderId: string; gatewayPaymentId?: string };
declare function findOrderByGatewayPaymentId(id: string): Order | undefined;
declare function findOrderById(orderId: string): Order | undefined;
declare function fulfillOrder(order: Order, gatewayPaymentId: string): Promise<void>;

const client = createPaymentClient({
  gateways: {
    stripe: stripeGateway({
      secretKey: process.env.STRIPE_SECRET_KEY!,
      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
    }),
  },
  defaultGateway: "stripe",
  // WEBHOOKS-2: no onWebhookVerified fulfillment. Verify-only client.
});

const engine = createWebhookInboxEngine({
  store,
  mode: "inline",
});

function isPaidFulfillmentEvent(event: unknown): boolean {
  if (event === null || typeof event !== "object") return false;
  const rec = event as { type?: unknown; payment?: { status?: unknown } };
  return (
    (rec.type === "payment.succeeded" || rec.type === "capture.completed") &&
    rec.payment?.status === "paid"
  );
}

export async function onStripeWebhook(rawBody: string, headers: Headers): Promise<Response> {
  const result = await processWebhookHttp({
    gateway: "stripe",
    rawBody, // string | Uint8Array from request.text() — do not JSON.parse
    headers,
    client,
    engine,
    handler: async (ctx) => {
      if (!isPaidFulfillmentEvent(ctx.event)) return;
      const event = ctx.event as {
        payment?: { references?: { providerObjectId?: string; internalReference?: string } };
      };
      const gatewayPaymentId = event.payment?.references?.providerObjectId;
      if (typeof gatewayPaymentId !== "string" || gatewayPaymentId.length === 0) return;
      const byGw = findOrderByGatewayPaymentId(gatewayPaymentId);
      if (byGw) {
        await fulfillOrder(byGw, gatewayPaymentId);
        return;
      }
      const ref = event.payment?.references?.internalReference;
      if (ref) {
        const candidate = findOrderById(ref);
        if (candidate) {
          await fulfillOrder(candidate, gatewayPaymentId);
          return;
        }
      }
      throw new Error("no local order for paid webhook");
    },
  });
  return webhookHttpResultToResponse(result);
}

ProcessWebhookHttpInput:

WebhookHttpResult:

• status: number
• headers: Record<string, string> — always includes x-request-id; retry-after only on 503 when seconds are known
• body: { error: "invalid_webhook" } for forgery / missing required signature / invalid UTF-8; { outcome, reason } for scheduled_for_retry; { outcome, retryable } for handler_failed; otherwise { outcome }

webhookHttpResultToResponse builds a Response with content-type: application/json (if not already set) and JSON.stringify(result.body).

After outcome === "indeterminate" or reconciliationRequired on create, do not createPayment again — lookup + decideReconciliationPolicy only (Outcomes). That rule is independent of this package; the HTTP adapter never auto-routes a second gateway.

Raw body vs object-HMAC

rawBody stays a string (or fatal-UTF-8 decoded bytes) at the HTTP layer.

• String-HMAC (stripe, paypal, myfatoorah): the raw string is passed unchanged into handleWebhook. Do not JSON.parse / JSON.stringify.
• Object-HMAC (tap, moyasar, paymob — OBJECT_HMAC_GATEWAYS): processWebhookHttp defensively JSON.parses a JSON object and passes that object. Arrays and invalid JSON stay the raw string (fail-closed at the verifier).
• No signature — enquiry-verified (hesabe): the raw string is passed unchanged; the adapter parses it and verifies facts through an async transaction-enquiry round trip inside handleWebhook.

Signature profiles

GATEWAY_WEBHOOK_SIGNATURE (keys lowercased at lookup):

extractWebhookSignature(gateway, headers, query?, profile?) returns a string, a lowercased header record (PayPal), or undefined. Unknown gateways return undefined (no early 400 from a missing profile).

hesabe has no entry. No signature header is required and no early 400 is emitted; the body is forwarded to handleWebhook, which awaits the adapter’s verifyWebhookAsync (transaction enquiry). A failed verification is forgery-class → 400 { error: "invalid_webhook" }; an enquiry transport failure throws → 500 { outcome: "handler_failed", retryable: true } so an authentic but unverifiable notification is redelivered. See Hesabe.

Failure paths

Parse-stage and missing-config errors are retryable 500 so the provider redelivers an authentic paid event instead of treating it as forgery. Do not map those to 400.

Headers always include x-request-id (from correlationId, else x-request-id → x-correlation-id → cf-ray → crypto.randomUUID() / timestamp fallback).

Header and env helpers

import {
  getHeader,
  resolveCorrelationId,
  requireStringBindings,
  extractWebhookSignature,
} from "@paykernel/integration-http";

getHeader(headers, "stripe-signature"); // case-insensitive; first non-empty array entry

const correlationId = resolveCorrelationId(headers);
// x-request-id → x-correlation-id → cf-ray → generated id

const { STRIPE_WEBHOOK_SECRET } = requireStringBindings(env, ["STRIPE_WEBHOOK_SECRET"]);
// throws `missing env: KEY, ...` listing keys only, never values

HeaderBag is Headers | Record<string, string | string[] | undefined>. Empty strings are treated as missing.

Other exports

Test-only memory inbox stores come from @paykernel/testkit (createMemoryWebhookInboxStore) and are NON-PRODUCTION. Do not use them as a multi-host store. See Stores and Webhooks.

Framework wrappers: Hono, Elysia, Express, Cloudflare Workers.