@webhooks-cc/sdk 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -73,7 +73,7 @@ interface SendOptions {
     /** Request body (will be JSON-serialized if not a string) */
     body?: unknown;
 }
-type TemplateProvider = "stripe" | "github" | "shopify" | "twilio";
+type TemplateProvider = "stripe" | "github" | "shopify" | "twilio" | "standard-webhooks";
 /**
  * Options for sending a provider template webhook with signed headers.
  */
@@ -172,10 +172,34 @@ interface OperationDescription {
     description: string;
     params: Record<string, string>;
 }
+/**
+ * Options for sending a webhook directly to an arbitrary URL.
+ * Supports optional provider signing (Standard Webhooks, Stripe, etc.).
+ */
+interface SendToOptions {
+    /** Provider template for signing (optional). When set, secret is required. */
+    provider?: TemplateProvider;
+    /** Provider-specific template preset (e.g. "checkout.session.completed" for Stripe) */
+    template?: string;
+    /** Secret for provider signature generation (required when provider is set) */
+    secret?: string;
+    /** Event name for provider headers */
+    event?: string;
+    /** HTTP method (default: "POST") */
+    method?: string;
+    /** HTTP headers to include */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON-serialized if not a string) */
+    body?: unknown;
+    /** Unix timestamp (seconds) override for deterministic signatures in tests */
+    timestamp?: number;
+}
 /** Self-describing schema returned by client.describe(). */
 interface SDKDescription {
     version: string;
     endpoints: Record<string, OperationDescription>;
+    sendTo: OperationDescription;
+    buildRequest: OperationDescription;
     requests: Record<string, OperationDescription>;
 }
 
@@ -252,6 +276,31 @@ declare class WebhooksCC {
         send: (slug: string, options?: SendOptions) => Promise<Response>;
         sendTemplate: (slug: string, options: SendTemplateOptions) => Promise<Response>;
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    buildRequest: (url: string, options?: SendToOptions) => Promise<{
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }>;
+    /**
+     * Send a webhook directly to any URL with optional provider signing.
+     * Use this for local integration testing — send properly signed webhooks
+     * to localhost handlers without routing through webhooks.cc infrastructure.
+     *
+     * @param url - Target URL to send the webhook to (http or https)
+     * @param options - Method, headers, body, and optional provider signing
+     * @returns Raw fetch Response from the target
+     */
+    sendTo: (url: string, options?: SendToOptions) => Promise<Response>;
     requests: {
         list: (endpointSlug: string, options?: ListRequestsOptions) => Promise<Request[]>;
         get: (requestId: string) => Promise<Request>;
@@ -325,6 +374,12 @@ declare function isTwilioWebhook(request: Request): boolean;
 declare function isPaddleWebhook(request: Request): boolean;
 /** Check if a request looks like a Linear webhook. */
 declare function isLinearWebhook(request: Request): boolean;
+/**
+ * Check if a request looks like a Standard Webhooks request.
+ * Matches on the presence of all three Standard Webhooks headers:
+ * webhook-id, webhook-timestamp, and webhook-signature.
+ */
+declare function isStandardWebhook(request: Request): boolean;
 
 /** Match requests by HTTP method (case-insensitive). */
 declare function matchMethod(method: string): (request: Request) => boolean;
@@ -376,4 +431,4 @@ interface SSEFrame {
  */
 declare function parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEFrame, void, undefined>;
 
-export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, type OperationDescription, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, type SDKDescription, type SSEFrame, type SendOptions, type SendTemplateOptions, type SubscribeOptions, type TemplateProvider, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };
+export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, type OperationDescription, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, type SDKDescription, type SSEFrame, type SendOptions, type SendTemplateOptions, type SendToOptions, type SubscribeOptions, type TemplateProvider, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStandardWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };

package/dist/index.d.ts

@@ -73,7 +73,7 @@ interface SendOptions {
     /** Request body (will be JSON-serialized if not a string) */
     body?: unknown;
 }
-type TemplateProvider = "stripe" | "github" | "shopify" | "twilio";
+type TemplateProvider = "stripe" | "github" | "shopify" | "twilio" | "standard-webhooks";
 /**
  * Options for sending a provider template webhook with signed headers.
  */
@@ -172,10 +172,34 @@ interface OperationDescription {
     description: string;
     params: Record<string, string>;
 }
+/**
+ * Options for sending a webhook directly to an arbitrary URL.
+ * Supports optional provider signing (Standard Webhooks, Stripe, etc.).
+ */
+interface SendToOptions {
+    /** Provider template for signing (optional). When set, secret is required. */
+    provider?: TemplateProvider;
+    /** Provider-specific template preset (e.g. "checkout.session.completed" for Stripe) */
+    template?: string;
+    /** Secret for provider signature generation (required when provider is set) */
+    secret?: string;
+    /** Event name for provider headers */
+    event?: string;
+    /** HTTP method (default: "POST") */
+    method?: string;
+    /** HTTP headers to include */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON-serialized if not a string) */
+    body?: unknown;
+    /** Unix timestamp (seconds) override for deterministic signatures in tests */
+    timestamp?: number;
+}
 /** Self-describing schema returned by client.describe(). */
 interface SDKDescription {
     version: string;
     endpoints: Record<string, OperationDescription>;
+    sendTo: OperationDescription;
+    buildRequest: OperationDescription;
     requests: Record<string, OperationDescription>;
 }
 
@@ -252,6 +276,31 @@ declare class WebhooksCC {
         send: (slug: string, options?: SendOptions) => Promise<Response>;
         sendTemplate: (slug: string, options: SendTemplateOptions) => Promise<Response>;
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    buildRequest: (url: string, options?: SendToOptions) => Promise<{
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }>;
+    /**
+     * Send a webhook directly to any URL with optional provider signing.
+     * Use this for local integration testing — send properly signed webhooks
+     * to localhost handlers without routing through webhooks.cc infrastructure.
+     *
+     * @param url - Target URL to send the webhook to (http or https)
+     * @param options - Method, headers, body, and optional provider signing
+     * @returns Raw fetch Response from the target
+     */
+    sendTo: (url: string, options?: SendToOptions) => Promise<Response>;
     requests: {
         list: (endpointSlug: string, options?: ListRequestsOptions) => Promise<Request[]>;
         get: (requestId: string) => Promise<Request>;
@@ -325,6 +374,12 @@ declare function isTwilioWebhook(request: Request): boolean;
 declare function isPaddleWebhook(request: Request): boolean;
 /** Check if a request looks like a Linear webhook. */
 declare function isLinearWebhook(request: Request): boolean;
+/**
+ * Check if a request looks like a Standard Webhooks request.
+ * Matches on the presence of all three Standard Webhooks headers:
+ * webhook-id, webhook-timestamp, and webhook-signature.
+ */
+declare function isStandardWebhook(request: Request): boolean;
 
 /** Match requests by HTTP method (case-insensitive). */
 declare function matchMethod(method: string): (request: Request) => boolean;
@@ -376,4 +431,4 @@ interface SSEFrame {
  */
 declare function parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEFrame, void, undefined>;
 
-export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, type OperationDescription, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, type SDKDescription, type SSEFrame, type SendOptions, type SendTemplateOptions, type SubscribeOptions, type TemplateProvider, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };
+export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, type OperationDescription, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, type SDKDescription, type SSEFrame, type SendOptions, type SendTemplateOptions, type SendToOptions, type SubscribeOptions, type TemplateProvider, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStandardWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   isPaddleWebhook: () => isPaddleWebhook,
   isShopifyWebhook: () => isShopifyWebhook,
   isSlackWebhook: () => isSlackWebhook,
+  isStandardWebhook: () => isStandardWebhook,
   isStripeWebhook: () => isStripeWebhook,
   isTwilioWebhook: () => isTwilioWebhook,
   matchAll: () => matchAll,
@@ -721,6 +722,33 @@ function toBase64(bytes) {
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary);
 }
+function fromBase64(str) {
+  if (typeof atob !== "function") {
+    return new Uint8Array(Buffer.from(str, "base64"));
+  }
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+async function hmacSignRaw(algorithm, keyBytes, payload) {
+  if (!globalThis.crypto?.subtle) {
+    throw new Error("crypto.subtle is required for signature generation");
+  }
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    keyBytes.buffer,
+    { name: "HMAC", hash: algorithm },
+    false,
+    ["sign"]
+  );
+  const signature = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(payload)
+  );
+  return new Uint8Array(signature);
+}
 function buildTwilioSignaturePayload(endpointUrl, params) {
   const sortedParams = params.map(([key, value], index) => ({ key, value, index })).sort(
     (a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : a.value < b.value ? -1 : a.value > b.value ? 1 : 0
@@ -732,35 +760,68 @@ function buildTwilioSignaturePayload(endpointUrl, params) {
   return payload;
 }
 async function buildTemplateSendOptions(endpointUrl, options) {
+  if (options.provider === "standard-webhooks") {
+    const method2 = (options.method ?? "POST").toUpperCase();
+    const payload = options.body ?? {};
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const msgId = options.event ? `msg_${options.event}_${randomHex(8)}` : `msg_${randomHex(16)}`;
+    const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
+    const signingInput = `${msgId}.${timestamp}.${body}`;
+    let rawSecret = options.secret;
+    const hadPrefix = rawSecret.startsWith("whsec_");
+    if (hadPrefix) {
+      rawSecret = rawSecret.slice(6);
+    }
+    let secretBytes;
+    try {
+      secretBytes = fromBase64(rawSecret);
+    } catch {
+      const raw = hadPrefix ? options.secret : rawSecret;
+      secretBytes = new TextEncoder().encode(raw);
+    }
+    const signature = await hmacSignRaw("SHA-256", secretBytes, signingInput);
+    return {
+      method: method2,
+      headers: {
+        "content-type": "application/json",
+        "webhook-id": msgId,
+        "webhook-timestamp": String(timestamp),
+        "webhook-signature": `v1,${toBase64(signature)}`,
+        ...options.headers ?? {}
+      },
+      body
+    };
+  }
+  const provider = options.provider;
   const method = (options.method ?? "POST").toUpperCase();
-  const template = ensureTemplate(options.provider, options.template);
-  const event = options.event ?? defaultEvent(options.provider, template);
+  const template = ensureTemplate(provider, options.template);
+  const event = options.event ?? defaultEvent(provider, template);
   const now = /* @__PURE__ */ new Date();
-  const built = buildTemplatePayload(options.provider, template, event, now, options.body);
+  const built = buildTemplatePayload(provider, template, event, now, options.body);
   const headers = {
     "content-type": built.contentType,
-    "x-webhooks-cc-template-provider": options.provider,
+    "x-webhooks-cc-template-provider": provider,
     "x-webhooks-cc-template-template": template,
     "x-webhooks-cc-template-event": event,
     ...built.headers
   };
-  if (options.provider === "stripe") {
+  if (provider === "stripe") {
     const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
     const signature = await hmacSign("SHA-256", options.secret, `${timestamp}.${built.body}`);
     headers["stripe-signature"] = `t=${timestamp},v1=${toHex(signature)}`;
   }
-  if (options.provider === "github") {
+  if (provider === "github") {
     headers["x-github-event"] = event;
     headers["x-github-delivery"] = randomUuid();
     const signature = await hmacSign("SHA-256", options.secret, built.body);
     headers["x-hub-signature-256"] = `sha256=${toHex(signature)}`;
   }
-  if (options.provider === "shopify") {
+  if (provider === "shopify") {
     headers["x-shopify-topic"] = event;
     const signature = await hmacSign("SHA-256", options.secret, built.body);
     headers["x-shopify-hmac-sha256"] = toBase64(signature);
   }
-  if (options.provider === "twilio") {
+  if (provider === "twilio") {
     const signaturePayload = built.twilioParams ? buildTwilioSignaturePayload(endpointUrl, built.twilioParams) : `${endpointUrl}${built.body}`;
     const signature = await hmacSign("SHA-1", options.secret, signaturePayload);
     headers["x-twilio-signature"] = toBase64(signature);
@@ -779,7 +840,7 @@ async function buildTemplateSendOptions(endpointUrl, options) {
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_WEBHOOK_URL = "https://go.webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.6.0";
 var MIN_POLL_INTERVAL = 10;
 var MAX_POLL_INTERVAL = 6e4;
 var ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]);
@@ -902,6 +963,123 @@ var WebhooksCC = class {
         return this.endpoints.send(slug, sendOptions);
       }
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    this.buildRequest = async (url, options = {}) => {
+      let parsed;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: "${url}" is not a valid URL`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Invalid URL: only http and https protocols are supported");
+      }
+      if (options.provider) {
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("buildRequest with a provider requires a non-empty secret");
+        }
+        const sendOptions = await buildTemplateSendOptions(url, {
+          provider: options.provider,
+          template: options.template,
+          secret: options.secret,
+          event: options.event,
+          body: options.body,
+          method: options.method,
+          headers: options.headers,
+          timestamp: options.timestamp
+        });
+        return {
+          url,
+          method: (sendOptions.method ?? "POST").toUpperCase(),
+          headers: sendOptions.headers ?? {},
+          body: sendOptions.body !== void 0 ? typeof sendOptions.body === "string" ? sendOptions.body : JSON.stringify(sendOptions.body) : void 0
+        };
+      }
+      const method = (options.method ?? "POST").toUpperCase();
+      if (!ALLOWED_METHODS.has(method)) {
+        throw new Error(
+          `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+        );
+      }
+      const headers = { ...options.headers ?? {} };
+      const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+      if (options.body !== void 0 && !hasContentType) {
+        headers["Content-Type"] = "application/json";
+      }
+      return {
+        url,
+        method,
+        headers,
+        body: options.body !== void 0 ? typeof options.body === "string" ? options.body : JSON.stringify(options.body) : void 0
+      };
+    };
+    /**
+     * Send a webhook directly to any URL with optional provider signing.
+     * Use this for local integration testing — send properly signed webhooks
+     * to localhost handlers without routing through webhooks.cc infrastructure.
+     *
+     * @param url - Target URL to send the webhook to (http or https)
+     * @param options - Method, headers, body, and optional provider signing
+     * @returns Raw fetch Response from the target
+     */
+    this.sendTo = async (url, options = {}) => {
+      let parsed;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: "${url}" is not a valid URL`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Invalid URL: only http and https protocols are supported");
+      }
+      if (options.provider) {
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("sendTo with a provider requires a non-empty secret");
+        }
+        const sendOptions = await buildTemplateSendOptions(url, {
+          provider: options.provider,
+          template: options.template,
+          secret: options.secret,
+          event: options.event,
+          body: options.body,
+          method: options.method,
+          headers: options.headers,
+          timestamp: options.timestamp
+        });
+        const method2 = (sendOptions.method ?? "POST").toUpperCase();
+        return fetch(url, {
+          method: method2,
+          headers: sendOptions.headers ?? {},
+          body: sendOptions.body !== void 0 ? typeof sendOptions.body === "string" ? sendOptions.body : JSON.stringify(sendOptions.body) : void 0,
+          signal: AbortSignal.timeout(this.timeout)
+        });
+      }
+      const method = (options.method ?? "POST").toUpperCase();
+      if (!ALLOWED_METHODS.has(method)) {
+        throw new Error(
+          `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+        );
+      }
+      const headers = { ...options.headers ?? {} };
+      const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+      if (options.body !== void 0 && !hasContentType) {
+        headers["Content-Type"] = "application/json";
+      }
+      return fetch(url, {
+        method,
+        headers,
+        body: options.body !== void 0 ? typeof options.body === "string" ? options.body : JSON.stringify(options.body) : void 0,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    };
     this.requests = {
       list: async (endpointSlug, options = {}) => {
         validatePathSegment(endpointSlug, "endpointSlug");
@@ -1250,13 +1428,33 @@ var WebhooksCC = class {
           description: "Send a provider template webhook with signed headers",
           params: {
             slug: "string",
-            provider: '"stripe"|"github"|"shopify"|"twilio"',
+            provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"',
             template: "string?",
             secret: "string",
             event: "string?"
           }
         }
       },
+      sendTo: {
+        description: "Send a webhook directly to any URL with optional provider signing",
+        params: {
+          url: "string",
+          provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"?',
+          secret: "string?",
+          body: "unknown?",
+          headers: "Record<string, string>?"
+        }
+      },
+      buildRequest: {
+        description: "Build a request without sending it \u2014 returns computed method, URL, headers, and body including provider signatures",
+        params: {
+          url: "string",
+          provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"?',
+          secret: "string?",
+          body: "unknown?",
+          headers: "Record<string, string>?"
+        }
+      },
       requests: {
         list: {
           description: "List captured requests",
@@ -1333,6 +1531,10 @@ function isPaddleWebhook(request) {
 function isLinearWebhook(request) {
   return Object.keys(request.headers).some((k) => k.toLowerCase() === "linear-signature");
 }
+function isStandardWebhook(request) {
+  const keys = Object.keys(request.headers).map((k) => k.toLowerCase());
+  return keys.includes("webhook-id") && keys.includes("webhook-timestamp") && keys.includes("webhook-signature");
+}
 
 // src/matchers.ts
 function matchMethod(method) {
@@ -1392,6 +1594,7 @@ function matchAny(first, ...rest) {
   isPaddleWebhook,
   isShopifyWebhook,
   isSlackWebhook,
+  isStandardWebhook,
   isStripeWebhook,
   isTwilioWebhook,
   matchAll,

package/dist/index.mjs

@@ -673,6 +673,33 @@ function toBase64(bytes) {
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary);
 }
+function fromBase64(str) {
+  if (typeof atob !== "function") {
+    return new Uint8Array(Buffer.from(str, "base64"));
+  }
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+async function hmacSignRaw(algorithm, keyBytes, payload) {
+  if (!globalThis.crypto?.subtle) {
+    throw new Error("crypto.subtle is required for signature generation");
+  }
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    keyBytes.buffer,
+    { name: "HMAC", hash: algorithm },
+    false,
+    ["sign"]
+  );
+  const signature = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(payload)
+  );
+  return new Uint8Array(signature);
+}
 function buildTwilioSignaturePayload(endpointUrl, params) {
   const sortedParams = params.map(([key, value], index) => ({ key, value, index })).sort(
     (a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : a.value < b.value ? -1 : a.value > b.value ? 1 : 0
@@ -684,35 +711,68 @@ function buildTwilioSignaturePayload(endpointUrl, params) {
   return payload;
 }
 async function buildTemplateSendOptions(endpointUrl, options) {
+  if (options.provider === "standard-webhooks") {
+    const method2 = (options.method ?? "POST").toUpperCase();
+    const payload = options.body ?? {};
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const msgId = options.event ? `msg_${options.event}_${randomHex(8)}` : `msg_${randomHex(16)}`;
+    const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
+    const signingInput = `${msgId}.${timestamp}.${body}`;
+    let rawSecret = options.secret;
+    const hadPrefix = rawSecret.startsWith("whsec_");
+    if (hadPrefix) {
+      rawSecret = rawSecret.slice(6);
+    }
+    let secretBytes;
+    try {
+      secretBytes = fromBase64(rawSecret);
+    } catch {
+      const raw = hadPrefix ? options.secret : rawSecret;
+      secretBytes = new TextEncoder().encode(raw);
+    }
+    const signature = await hmacSignRaw("SHA-256", secretBytes, signingInput);
+    return {
+      method: method2,
+      headers: {
+        "content-type": "application/json",
+        "webhook-id": msgId,
+        "webhook-timestamp": String(timestamp),
+        "webhook-signature": `v1,${toBase64(signature)}`,
+        ...options.headers ?? {}
+      },
+      body
+    };
+  }
+  const provider = options.provider;
   const method = (options.method ?? "POST").toUpperCase();
-  const template = ensureTemplate(options.provider, options.template);
-  const event = options.event ?? defaultEvent(options.provider, template);
+  const template = ensureTemplate(provider, options.template);
+  const event = options.event ?? defaultEvent(provider, template);
   const now = /* @__PURE__ */ new Date();
-  const built = buildTemplatePayload(options.provider, template, event, now, options.body);
+  const built = buildTemplatePayload(provider, template, event, now, options.body);
   const headers = {
     "content-type": built.contentType,
-    "x-webhooks-cc-template-provider": options.provider,
+    "x-webhooks-cc-template-provider": provider,
     "x-webhooks-cc-template-template": template,
     "x-webhooks-cc-template-event": event,
     ...built.headers
   };
-  if (options.provider === "stripe") {
+  if (provider === "stripe") {
     const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
     const signature = await hmacSign("SHA-256", options.secret, `${timestamp}.${built.body}`);
     headers["stripe-signature"] = `t=${timestamp},v1=${toHex(signature)}`;
   }
-  if (options.provider === "github") {
+  if (provider === "github") {
     headers["x-github-event"] = event;
     headers["x-github-delivery"] = randomUuid();
     const signature = await hmacSign("SHA-256", options.secret, built.body);
     headers["x-hub-signature-256"] = `sha256=${toHex(signature)}`;
   }
-  if (options.provider === "shopify") {
+  if (provider === "shopify") {
     headers["x-shopify-topic"] = event;
     const signature = await hmacSign("SHA-256", options.secret, built.body);
     headers["x-shopify-hmac-sha256"] = toBase64(signature);
   }
-  if (options.provider === "twilio") {
+  if (provider === "twilio") {
     const signaturePayload = built.twilioParams ? buildTwilioSignaturePayload(endpointUrl, built.twilioParams) : `${endpointUrl}${built.body}`;
     const signature = await hmacSign("SHA-1", options.secret, signaturePayload);
     headers["x-twilio-signature"] = toBase64(signature);
@@ -731,7 +791,7 @@ async function buildTemplateSendOptions(endpointUrl, options) {
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_WEBHOOK_URL = "https://go.webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.6.0";
 var MIN_POLL_INTERVAL = 10;
 var MAX_POLL_INTERVAL = 6e4;
 var ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]);
@@ -854,6 +914,123 @@ var WebhooksCC = class {
         return this.endpoints.send(slug, sendOptions);
       }
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    this.buildRequest = async (url, options = {}) => {
+      let parsed;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: "${url}" is not a valid URL`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Invalid URL: only http and https protocols are supported");
+      }
+      if (options.provider) {
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("buildRequest with a provider requires a non-empty secret");
+        }
+        const sendOptions = await buildTemplateSendOptions(url, {
+          provider: options.provider,
+          template: options.template,
+          secret: options.secret,
+          event: options.event,
+          body: options.body,
+          method: options.method,
+          headers: options.headers,
+          timestamp: options.timestamp
+        });
+        return {
+          url,
+          method: (sendOptions.method ?? "POST").toUpperCase(),
+          headers: sendOptions.headers ?? {},
+          body: sendOptions.body !== void 0 ? typeof sendOptions.body === "string" ? sendOptions.body : JSON.stringify(sendOptions.body) : void 0
+        };
+      }
+      const method = (options.method ?? "POST").toUpperCase();
+      if (!ALLOWED_METHODS.has(method)) {
+        throw new Error(
+          `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+        );
+      }
+      const headers = { ...options.headers ?? {} };
+      const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+      if (options.body !== void 0 && !hasContentType) {
+        headers["Content-Type"] = "application/json";
+      }
+      return {
+        url,
+        method,
+        headers,
+        body: options.body !== void 0 ? typeof options.body === "string" ? options.body : JSON.stringify(options.body) : void 0
+      };
+    };
+    /**
+     * Send a webhook directly to any URL with optional provider signing.
+     * Use this for local integration testing — send properly signed webhooks
+     * to localhost handlers without routing through webhooks.cc infrastructure.
+     *
+     * @param url - Target URL to send the webhook to (http or https)
+     * @param options - Method, headers, body, and optional provider signing
+     * @returns Raw fetch Response from the target
+     */
+    this.sendTo = async (url, options = {}) => {
+      let parsed;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: "${url}" is not a valid URL`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Invalid URL: only http and https protocols are supported");
+      }
+      if (options.provider) {
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("sendTo with a provider requires a non-empty secret");
+        }
+        const sendOptions = await buildTemplateSendOptions(url, {
+          provider: options.provider,
+          template: options.template,
+          secret: options.secret,
+          event: options.event,
+          body: options.body,
+          method: options.method,
+          headers: options.headers,
+          timestamp: options.timestamp
+        });
+        const method2 = (sendOptions.method ?? "POST").toUpperCase();
+        return fetch(url, {
+          method: method2,
+          headers: sendOptions.headers ?? {},
+          body: sendOptions.body !== void 0 ? typeof sendOptions.body === "string" ? sendOptions.body : JSON.stringify(sendOptions.body) : void 0,
+          signal: AbortSignal.timeout(this.timeout)
+        });
+      }
+      const method = (options.method ?? "POST").toUpperCase();
+      if (!ALLOWED_METHODS.has(method)) {
+        throw new Error(
+          `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+        );
+      }
+      const headers = { ...options.headers ?? {} };
+      const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+      if (options.body !== void 0 && !hasContentType) {
+        headers["Content-Type"] = "application/json";
+      }
+      return fetch(url, {
+        method,
+        headers,
+        body: options.body !== void 0 ? typeof options.body === "string" ? options.body : JSON.stringify(options.body) : void 0,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    };
     this.requests = {
       list: async (endpointSlug, options = {}) => {
         validatePathSegment(endpointSlug, "endpointSlug");
@@ -1202,13 +1379,33 @@ var WebhooksCC = class {
           description: "Send a provider template webhook with signed headers",
           params: {
             slug: "string",
-            provider: '"stripe"|"github"|"shopify"|"twilio"',
+            provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"',
             template: "string?",
             secret: "string",
             event: "string?"
           }
         }
       },
+      sendTo: {
+        description: "Send a webhook directly to any URL with optional provider signing",
+        params: {
+          url: "string",
+          provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"?',
+          secret: "string?",
+          body: "unknown?",
+          headers: "Record<string, string>?"
+        }
+      },
+      buildRequest: {
+        description: "Build a request without sending it \u2014 returns computed method, URL, headers, and body including provider signatures",
+        params: {
+          url: "string",
+          provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"?',
+          secret: "string?",
+          body: "unknown?",
+          headers: "Record<string, string>?"
+        }
+      },
       requests: {
         list: {
           description: "List captured requests",
@@ -1285,6 +1482,10 @@ function isPaddleWebhook(request) {
 function isLinearWebhook(request) {
   return Object.keys(request.headers).some((k) => k.toLowerCase() === "linear-signature");
 }
+function isStandardWebhook(request) {
+  const keys = Object.keys(request.headers).map((k) => k.toLowerCase());
+  return keys.includes("webhook-id") && keys.includes("webhook-timestamp") && keys.includes("webhook-signature");
+}
 
 // src/matchers.ts
 function matchMethod(method) {
@@ -1343,6 +1544,7 @@ export {
   isPaddleWebhook,
   isShopifyWebhook,
   isSlackWebhook,
+  isStandardWebhook,
   isStripeWebhook,
   isTwilioWebhook,
   matchAll,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webhooks-cc/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeScript SDK for webhooks.cc — create endpoints, capture requests, assert in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",