@voyant-travel/webhook-delivery 0.3.4 → 0.4.0

package/dist/app-envelope.d.ts

@@ -0,0 +1,41 @@
+import type { EventEnvelope } from "@voyant-travel/core";
+import type { ExternalWebhookEventContract } from "./contracts.js";
+export interface AppWebhookDeliveryEnvelope {
+    schema: "voyant.app-webhook.delivery.v1";
+    deliveryId: string;
+    installationId: string;
+    appId: string;
+    event: {
+        type: string;
+        schemaVersion: string;
+        occurredAt: string;
+        deliveredAt: string;
+    };
+    attempt: {
+        number: number;
+        maxRetries: number;
+        idempotencyKey: string;
+        originalDeliveryId: string | null;
+        parentDeliveryId: string | null;
+    };
+    subject: {
+        module: string | null;
+        id: string | null;
+    };
+    payload: unknown;
+    metadata: Record<string, unknown>;
+}
+export declare function createAppWebhookDeliveryEnvelope(input: {
+    deliveryId: string;
+    installationId: string;
+    appId: string;
+    event: EventEnvelope;
+    contract: ExternalWebhookEventContract;
+    deliveredAt: Date;
+    attemptNumber: number;
+    maxRetries: number;
+    idempotencyKey: string;
+    originalDeliveryId?: string | null;
+    parentDeliveryId?: string | null;
+}): AppWebhookDeliveryEnvelope;
+export declare function isAppWebhookDeliveryEnvelope(value: unknown): value is AppWebhookDeliveryEnvelope;

package/dist/app-envelope.js

@@ -0,0 +1,54 @@
+export function createAppWebhookDeliveryEnvelope(input) {
+    const subject = sourceEntity(input.event.data);
+    return {
+        schema: "voyant.app-webhook.delivery.v1",
+        deliveryId: input.deliveryId,
+        installationId: input.installationId,
+        appId: input.appId,
+        event: {
+            type: input.event.name,
+            schemaVersion: input.contract.eventVersion,
+            occurredAt: input.event.emittedAt,
+            deliveredAt: input.deliveredAt.toISOString(),
+        },
+        attempt: {
+            number: input.attemptNumber,
+            maxRetries: input.maxRetries,
+            idempotencyKey: input.idempotencyKey,
+            originalDeliveryId: input.originalDeliveryId ?? null,
+            parentDeliveryId: input.parentDeliveryId ?? null,
+        },
+        subject,
+        payload: input.event.data,
+        metadata: input.event.metadata ?? {},
+    };
+}
+export function isAppWebhookDeliveryEnvelope(value) {
+    return (isRecord(value) &&
+        value.schema === "voyant.app-webhook.delivery.v1" &&
+        typeof value.deliveryId === "string" &&
+        typeof value.installationId === "string" &&
+        typeof value.appId === "string" &&
+        isRecord(value.event) &&
+        typeof value.event.type === "string" &&
+        typeof value.event.schemaVersion === "string" &&
+        typeof value.event.occurredAt === "string" &&
+        typeof value.event.deliveredAt === "string" &&
+        isRecord(value.attempt) &&
+        typeof value.attempt.number === "number" &&
+        typeof value.attempt.idempotencyKey === "string" &&
+        "payload" in value);
+}
+function sourceEntity(data) {
+    if (!isRecord(data))
+        return { module: null, id: null };
+    const module = data.entityModule ?? data.entity_module;
+    const id = data.entityId ?? data.entity_id;
+    return {
+        module: typeof module === "string" ? module : null,
+        id: typeof id === "string" ? id : null,
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+export type { AppWebhookDeliveryEnvelope } from "./app-envelope.js";
+export { createAppWebhookDeliveryEnvelope, isAppWebhookDeliveryEnvelope } from "./app-envelope.js";
 export type { ExternalWebhookEventContract, WebhookSubscriptionEventInput, } from "./contracts.js";
 export { assertWebhookSubscriptionCreateEvents, assertWebhookSubscriptionUpdateEvents, prepareExternalWebhookEvent, } from "./contracts.js";
 export type { OutboundWebhookDeliveryEnqueuer, OutboundWebhookEnqueueProvider, ResolveOutboundWebhookDeliveryEnqueuerOptions, } from "./provider.js";
 export { resolveOutboundWebhookDeliveryEnqueuer } from "./provider.js";
-export { hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
+export type { WebhookSigningKey } from "./security.js";
+export { assertOutboundWebhookEndpointUrl, hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, verifyWebhookPayloadSignature, webhookBodyExcerpt, } from "./security.js";
 export type { CreateSelectedExternalWebhookQueueOptions } from "./selected-queue.js";
 export { createSelectedExternalWebhookQueue, externalContractFromEventMetadata, } from "./selected-queue.js";
 export type { WebhookSubscriptionMutationStore, WebhookSubscriptionService, } from "./subscriptions.js";

package/dist/index.js

@@ -1,6 +1,7 @@
+export { createAppWebhookDeliveryEnvelope, isAppWebhookDeliveryEnvelope } from "./app-envelope.js";
 export { assertWebhookSubscriptionCreateEvents, assertWebhookSubscriptionUpdateEvents, prepareExternalWebhookEvent, } from "./contracts.js";
 export { resolveOutboundWebhookDeliveryEnqueuer } from "./provider.js";
-export { hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
+export { assertOutboundWebhookEndpointUrl, hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, verifyWebhookPayloadSignature, webhookBodyExcerpt, } from "./security.js";
 export { createSelectedExternalWebhookQueue, externalContractFromEventMetadata, } from "./selected-queue.js";
 export { createWebhookSubscriptionService } from "./subscriptions.js";
 export { createWebhookDeliveryWorker } from "./worker.js";

package/dist/postgres-store.js

@@ -151,6 +151,7 @@ function toWebhookSubscription(row) {
         id: row.id,
         url: row.url,
         secret: row.secret,
+        keyId: null,
         headers: row.headers ?? null,
         maxRetries: row.maxRetries,
         active: row.active,
@@ -201,7 +202,7 @@ function requireSubscription(row, operation) {
 }
 function pendingAttemptValues(input) {
     return {
-        id: newId("webhook_deliveries"),
+        id: input.id ?? newId("webhook_deliveries"),
         sourceModule: input.sourceModule,
         sourceEvent: input.sourceEvent,
         sourceEntityModule: input.sourceEntityModule,

package/dist/security.d.ts

@@ -1,4 +1,23 @@
 export declare function signWebhookPayload(secret: string, timestamp: string, body: string): string;
+export interface WebhookSigningKey {
+    id: string;
+    secret: string;
+}
+export declare function verifyWebhookPayloadSignature(input: {
+    body: string;
+    timestamp: string;
+    signature: string;
+    keys: readonly WebhookSigningKey[];
+    now?: Date;
+    toleranceSeconds?: number;
+}): {
+    ok: true;
+    keyId: string;
+} | {
+    ok: false;
+    reason: string;
+};
 export declare function hashWebhookPayload(body: string): string;
+export declare function assertOutboundWebhookEndpointUrl(value: string): void;
 export declare function redactWebhookHeaders(headers: Record<string, string> | undefined): Record<string, string> | null;
 export declare function webhookBodyExcerpt(body: unknown, maxBytes?: number): string | null;

package/dist/security.js

@@ -1,4 +1,5 @@
 import { createHash, createHmac } from "node:crypto";
+import { isIP } from "node:net";
 const DEFAULT_EXCERPT_BYTES = 4 * 1024;
 const REDACTION_MARKER = "[REDACTED]";
 const REDACTED_HEADERS = new Set([
@@ -53,9 +54,45 @@ const PHONE_PATTERN = /\+?\d[\d\s().-]{6,}\d/g;
 export function signWebhookPayload(secret, timestamp, body) {
     return `sha256=${createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex")}`;
 }
+export function verifyWebhookPayloadSignature(input) {
+    const timestampSeconds = Number(input.timestamp);
+    if (!Number.isInteger(timestampSeconds))
+        return { ok: false, reason: "invalid_timestamp" };
+    const nowSeconds = Math.floor((input.now ?? new Date()).getTime() / 1_000);
+    const tolerance = input.toleranceSeconds ?? 300;
+    if (Math.abs(nowSeconds - timestampSeconds) > tolerance) {
+        return { ok: false, reason: "timestamp_outside_tolerance" };
+    }
+    for (const key of input.keys) {
+        if (signWebhookPayload(key.secret, input.timestamp, input.body) === input.signature) {
+            return { ok: true, keyId: key.id };
+        }
+    }
+    return { ok: false, reason: "signature_mismatch" };
+}
 export function hashWebhookPayload(body) {
     return createHash("sha256").update(body).digest("hex");
 }
+export function assertOutboundWebhookEndpointUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:") {
+        throw new Error(`Webhook URL must use HTTPS: ${value}`);
+    }
+    const hostname = url.hostname.toLowerCase();
+    const address = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+    if (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        hostname === "metadata.google.internal") {
+        throw new Error(`Webhook URL host is not allowed: ${hostname}`);
+    }
+    const ipVersion = isIP(address);
+    if (ipVersion === 4 && isPrivateIpv4(address)) {
+        throw new Error(`Webhook URL IP is not allowed: ${address}`);
+    }
+    if (ipVersion === 6 && isPrivateIpv6(address)) {
+        throw new Error(`Webhook URL IP is not allowed: ${address}`);
+    }
+}
 export function redactWebhookHeaders(headers) {
     if (!headers)
         return null;
@@ -109,3 +146,20 @@ function redactValue(value) {
 function redactString(value) {
     return value.replace(EMAIL_PATTERN, REDACTION_MARKER).replace(PHONE_PATTERN, REDACTION_MARKER);
 }
+function isPrivateIpv4(value) {
+    const [a = 0, b = 0] = value.split(".").map((part) => Number(part));
+    return (a === 10 ||
+        a === 127 ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        a === 0);
+}
+function isPrivateIpv6(value) {
+    const normalized = value.toLowerCase();
+    return (normalized === "::1" ||
+        normalized === "::" ||
+        normalized.startsWith("fc") ||
+        normalized.startsWith("fd") ||
+        normalized.startsWith("fe80:"));
+}

package/dist/selected-queue.js

@@ -1,4 +1,6 @@
 import { isExternalWebhookPayloadSchema } from "@voyant-travel/core/project";
+import { newId } from "@voyant-travel/db/lib/typeid";
+import { createAppWebhookDeliveryEnvelope } from "./app-envelope.js";
 import { prepareExternalWebhookEvent } from "./contracts.js";
 import { hashWebhookPayload, redactWebhookHeaders, webhookBodyExcerpt } from "./security.js";
 export function createSelectedExternalWebhookQueue(options) {
@@ -12,11 +14,28 @@ export function createSelectedExternalWebhookQueue(options) {
                 throw new Error(`Event "${input.name}" is not in the selected external catalog.`);
             }
             const event = prepareExternalWebhookEvent(input, contract);
-            const body = JSON.stringify(event);
             const subscriptions = await options.store.listActiveSubscriptions(event.name);
-            return Promise.all(subscriptions.map(async (subscription) => {
+            return Promise.all(subscriptions
+                .filter((subscription) => !subscription.app || subscription.app.eventVersion === contract.eventVersion)
+                .map(async (subscription) => {
+                const deliveryId = newId("webhook_deliveries");
                 const idempotencyKey = `graph-webhook:${eventId}:${subscription.id}`;
+                const payload = subscription.app
+                    ? createAppWebhookDeliveryEnvelope({
+                        deliveryId,
+                        installationId: subscription.app.installationId,
+                        appId: subscription.app.appId,
+                        event,
+                        contract,
+                        deliveredAt: now(),
+                        attemptNumber: 1,
+                        maxRetries: subscription.maxRetries,
+                        idempotencyKey,
+                    })
+                    : event;
+                const body = JSON.stringify(payload);
                 const enqueued = await options.store.enqueueAttempt({
+                    id: deliveryId,
                     sourceModule: stringMetadata(input, "graphEventSourceModule") ?? "graph-outbound-webhooks",
                     sourceEvent: event.name,
                     ...sourceEntity(event.data),
@@ -34,7 +53,7 @@ export function createSelectedExternalWebhookQueue(options) {
                     }) ?? {},
                     requestBodyHash: hashWebhookPayload(body),
                     requestBodyExcerpt: webhookBodyExcerpt(body),
-                    requestPayload: event,
+                    requestPayload: payload,
                     deliveryContract: contract,
                     attemptNumber: 1,
                     parentDeliveryId: null,

package/dist/types.d.ts

@@ -1,15 +1,23 @@
 import type { EventEnvelope } from "@voyant-travel/core";
 import type { InfraWebhookDelivery } from "@voyant-travel/db/schema/infra";
+import type { AppWebhookDeliveryEnvelope } from "./app-envelope.js";
 import type { ExternalWebhookEventContract } from "./contracts.js";
 export interface WebhookSubscription {
     id: string;
     url: string;
     secret: string;
+    keyId?: string | null;
     headers: Record<string, string> | null;
     maxRetries: number;
     active: boolean;
+    app?: {
+        installationId: string;
+        appId: string;
+        eventVersion: string;
+    };
 }
 export interface EnqueueWebhookAttemptInput {
+    id?: string;
     sourceModule: string;
     sourceEvent: string;
     sourceEntityModule: string | null;
@@ -20,7 +28,7 @@ export interface EnqueueWebhookAttemptInput {
     requestHeaders: Record<string, string>;
     requestBodyHash: string;
     requestBodyExcerpt: string | null;
-    requestPayload: EventEnvelope;
+    requestPayload: EventEnvelope | AppWebhookDeliveryEnvelope;
     deliveryContract: ExternalWebhookEventContract;
     attemptNumber: number;
     parentDeliveryId: string | null;

package/dist/worker.js

@@ -1,5 +1,7 @@
 import { isExternalWebhookPayloadSchema } from "@voyant-travel/core/project";
-import { hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
+import { newId } from "@voyant-travel/db/lib/typeid";
+import { createAppWebhookDeliveryEnvelope, isAppWebhookDeliveryEnvelope, } from "./app-envelope.js";
+import { assertOutboundWebhookEndpointUrl, hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
 const DEFAULT_BASE_DELAY_MS = 1_000;
 const DEFAULT_MAX_DELAY_MS = 60_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -45,7 +47,7 @@ export function createWebhookDeliveryWorker(options) {
         if (!subscription?.active) {
             return abandon(delivery, startedAt, "webhook subscription is unavailable or inactive");
         }
-        const body = JSON.stringify(hydrated.event);
+        const body = JSON.stringify(hydrated.payload);
         if (hashWebhookPayload(body) !== delivery.requestBodyHash) {
             return abandon(delivery, startedAt, "persisted webhook payload hash does not match");
         }
@@ -67,7 +69,7 @@ export function createWebhookDeliveryWorker(options) {
         }
         const mayRetry = result.retryable && delivery.attemptNumber <= subscription.maxRetries;
         if (mayRetry) {
-            const retry = retryInput(delivery, hydrated.event, hydrated.contract, subscription, body, finishedAt, baseDelayMs, maxDelayMs);
+            const retry = retryInput(delivery, hydrated.payload, hydrated.contract, subscription, finishedAt, baseDelayMs, maxDelayMs);
             const persisted = await options.store.completeAndEnqueueRetry({ ...completion, status: "failed" }, retry);
             const outcome = {
                 status: "retry_scheduled",
@@ -114,16 +116,32 @@ export function createWebhookDeliveryWorker(options) {
     }
 }
 function hydrateAttempt(delivery) {
-    if (!isEventEnvelope(delivery.requestPayload)) {
-        return { ok: false, reason: "pending webhook delivery has no complete request payload" };
-    }
     if (!isExternalContract(delivery.deliveryContract)) {
         return { ok: false, reason: "pending webhook delivery has no valid contract snapshot" };
     }
+    if (isAppWebhookDeliveryEnvelope(delivery.requestPayload)) {
+        if (delivery.requestPayload.event.type !== delivery.deliveryContract.eventType) {
+            return { ok: false, reason: "persisted webhook payload and contract event types differ" };
+        }
+        return {
+            ok: true,
+            event: eventFromAppEnvelope(delivery.requestPayload),
+            payload: delivery.requestPayload,
+            contract: delivery.deliveryContract,
+        };
+    }
+    if (!isEventEnvelope(delivery.requestPayload)) {
+        return { ok: false, reason: "pending webhook delivery has no complete request payload" };
+    }
     if (delivery.requestPayload.name !== delivery.deliveryContract.eventType) {
         return { ok: false, reason: "persisted webhook payload and contract event types differ" };
     }
-    return { ok: true, event: delivery.requestPayload, contract: delivery.deliveryContract };
+    return {
+        ok: true,
+        event: delivery.requestPayload,
+        payload: delivery.requestPayload,
+        contract: delivery.deliveryContract,
+    };
 }
 function isEventEnvelope(value) {
     return (isRecord(value) &&
@@ -138,8 +156,16 @@ function isExternalContract(value) {
         typeof value.eventVersion === "string" &&
         isExternalWebhookPayloadSchema(value.payloadSchema));
 }
+function eventFromAppEnvelope(envelope) {
+    return {
+        name: envelope.event.type,
+        data: envelope.payload,
+        emittedAt: envelope.event.occurredAt,
+        metadata: envelope.metadata,
+    };
+}
 async function dispatch(fetchImpl, url, headers, body, timeoutMs) {
-    assertWebhookUrl(url);
+    assertOutboundWebhookEndpointUrl(url);
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -186,9 +212,27 @@ async function dispatch(fetchImpl, url, headers, body, timeoutMs) {
         clearTimeout(timeout);
     }
 }
-function retryInput(delivery, event, contract, subscription, body, now, baseDelayMs, maxDelayMs) {
+function retryInput(delivery, payload, contract, subscription, now, baseDelayMs, maxDelayMs) {
     const nextAttempt = delivery.attemptNumber + 1;
+    const deliveryId = newId("webhook_deliveries");
+    const retryPayload = isAppWebhookDeliveryEnvelope(payload)
+        ? createAppWebhookDeliveryEnvelope({
+            deliveryId,
+            installationId: payload.installationId,
+            appId: payload.appId,
+            event: eventFromAppEnvelope(payload),
+            contract,
+            deliveredAt: now,
+            attemptNumber: nextAttempt,
+            maxRetries: subscription.maxRetries,
+            idempotencyKey: delivery.idempotencyKey ?? delivery.id,
+            originalDeliveryId: payload.attempt.originalDeliveryId ?? payload.deliveryId,
+            parentDeliveryId: delivery.id,
+        })
+        : payload;
+    const body = JSON.stringify(retryPayload);
     return {
+        id: deliveryId,
         sourceModule: delivery.sourceModule,
         sourceEvent: delivery.sourceEvent,
         sourceEntityModule: delivery.sourceEntityModule,
@@ -199,7 +243,7 @@ function retryInput(delivery, event, contract, subscription, body, now, baseDela
         requestHeaders: delivery.requestHeaders ?? {},
         requestBodyHash: hashWebhookPayload(body),
         requestBodyExcerpt: webhookBodyExcerpt(body),
-        requestPayload: event,
+        requestPayload: retryPayload,
         deliveryContract: contract,
         attemptNumber: nextAttempt,
         parentDeliveryId: delivery.id,
@@ -232,6 +276,13 @@ function signedHeaders(subscription, event, contract, idempotencyKey, timestamp,
         "x-voyant-event-contract": contract.eventId,
         "x-voyant-event-version": contract.eventVersion,
         "x-voyant-timestamp": timestamp,
+        ...(subscription.keyId ? { "x-voyant-key-id": subscription.keyId } : {}),
+        ...(subscription.app
+            ? {
+                "x-voyant-app-id": subscription.app.appId,
+                "x-voyant-installation-id": subscription.app.installationId,
+            }
+            : {}),
         "x-voyant-signature": signWebhookPayload(subscription.secret, timestamp, body),
     };
 }
@@ -302,12 +353,6 @@ function positiveInteger(value, fallback) {
 function boundedMessage(message) {
     return message.slice(0, MAX_ERROR_MESSAGE_LENGTH);
 }
-function assertWebhookUrl(value) {
-    const url = new URL(value);
-    if (url.protocol !== "https:" && url.protocol !== "http:") {
-        throw new Error(`Webhook URL must use HTTP(S): ${value}`);
-    }
-}
 function stringMetadata(event, key) {
     const value = event.metadata?.[key];
     return typeof value === "string" && value.length > 0 ? value : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/webhook-delivery",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Durable, policy-aware outbound webhook delivery for Voyant Node deployments.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,7 +20,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "@voyant-travel/core": "^0.125.0",
-    "@voyant-travel/db": "^0.114.9"
+    "@voyant-travel/db": "^0.114.10"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",