@hostwebhook/node 1.6.1 → 1.6.3

package/README.md

@@ -14,7 +14,7 @@ Requires Node.js 18+.
 
 ## Verify Webhook Signatures
 
-HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and prevent replay attacks.
+HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and to reject stale signatures (see [What is signed](#what-is-signed)).
 
 ### Express
 
@@ -86,7 +86,9 @@ try {
 }
 ```
 
-Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable replay protection.
+Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable the age check.
+
+`verify` and the middlewares refuse an empty signing secret (an unset environment variable is the usual cause): with an empty key anyone can compute a valid signature.
 
 ## Send Webhooks
 
@@ -113,7 +115,7 @@ const result = await hw.send(
   { waitForResult: true },
 );
 
-console.log(result.syncStatus);  // 200 = delivered, 422 = validation failed, 502 = failed, 408 = timeout
+console.log(result.syncStatus);  // 200 = delivered, 202 = paused, 422 = validation failed, 500 = failed, 408 = timeout
 console.log(result.steps);       // array of pipeline steps with nodeType, status, durationMs
 console.log(result.response);    // response body from target URL
 ```
@@ -187,7 +189,7 @@ Your endpoint has a **Response Mode** setting (None or Sync) that affects how `s
 |----------|--------------|------------|----------|
 | **Forms / UIs** | None | `onResult` | `send()` returns instantly. Pipeline result arrives in background callback. **UI never blocks.** |
 | **Backend scripts** | None | `waitForResult` | `send()` blocks until pipeline completes via SSE (~120s max). |
-| **API proxy / Stripe** | Sync | *(none)* | `send()` blocks until pipeline completes via HTTP (~120s max). Result is inline in the response. |
+| **API proxy / Stripe** | Sync | *(none)* | `send()` blocks until a Schema Validator or an AI Node in the flow answers (20s at most, 55s with an AI Node; `timeoutMs` is 60s by default, enough for both). A 2xx is the result; a 422, 500 or 408 throws `SendError` with the JSON body in `responseBody`. |
 | **Testing (Postman)** | Sync | *(none)* | Single request, response includes full pipeline result. |
 
 > **Warning: Never use Sync mode for user-facing forms or UIs.** Sync mode holds the HTTP connection open on the server, which blocks `send()` and freezes the UI until the pipeline completes. If the pipeline has approval nodes, merge nodes, or long delays, the SDK will timeout. Use **None** mode with `onResult` instead — the user sees "Sent!" immediately and the pipeline result arrives in the background.
@@ -214,7 +216,7 @@ Your endpoint has a **Response Mode** setting (None or Sync) that affects how `s
 | `signingSecret` | `string` | — | Signs outgoing requests with HMAC-SHA256 |
 | `signature` | `StaticSignature` | — | Static secret signature (alternative to HMAC) |
 | `defaultHeaders` | `Record<string, string>` | — | Headers added to every request |
-| `timeoutMs` | `number` | `10000` | Request timeout in ms |
+| `timeoutMs` | `number` | `60000` | Request timeout in ms (long enough for a Sync webhook) |
 
 ### SendOptions
 
@@ -259,6 +261,13 @@ X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>
 
 HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
 
+### What is signed
+
+The signature covers **only the timestamp and the raw body**. In particular:
+
+- The other `X-HostWebhook-*` headers — the event id, the attempt number and every `chain-*` header — are **not signed**. Anyone who can reach your endpoint can add or change them, so use them as hints (for example to deduplicate), never as proof.
+- The timestamp limits how **old** a signature may be (`maxAgeSec`). It does not stop the same signed request from being sent again inside that window: to reject duplicates, remember the event ids you already processed.
+
 ## Support
 
 Found a bug or have a feature request? [Report an issue](https://www.hostwebhook.com/#issues) on our website.

package/dist/index.d.mts

@@ -16,16 +16,28 @@ interface VerifyOptions {
  *
  * The HMAC is computed as: HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
  *
+ * What is signed: ONLY the timestamp and the raw body. The other
+ * `X-HostWebhook-*` headers (event id, attempt, chain-*) are NOT covered by the
+ * signature: anyone who can reach your endpoint can add or change them. Do not
+ * make security decisions from them. And the timestamp only limits how OLD a
+ * signature may be (`maxAgeSec`); it does not stop the same signed request from
+ * being replayed inside that window. To reject duplicates, remember the event
+ * id of what you already processed.
+ *
  * @param payload - The raw request body (string or Buffer)
  * @param headers - The request headers object
  * @param secret  - Your signing secret (e.g. `whsec_...`)
  * @param options - Optional configuration
- * @throws {VerificationError} If the signature is missing, malformed, expired, or invalid
+ * @throws {VerificationError} If the secret is empty, or the signature is missing, malformed, expired, or invalid
  */
 declare function verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: VerifyOptions): void;
 
 /**
  * Typed representation of HostWebhook delivery headers.
+ *
+ * ⚠️ Only `timestamp` and the body are covered by the signature. The event id,
+ * the attempt number and every `chain*` field come from headers that are NOT
+ * signed: treat them as hints (for example to deduplicate), never as proof.
  */
 interface WebhookHeaders {
     /** Unique event ID (`X-HostWebhook-Event-Id`) */
@@ -220,7 +232,7 @@ interface HostWebhookConfig {
     signature?: StaticSignature;
     /** Custom headers to include in every request. */
     defaultHeaders?: Record<string, string>;
-    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    /** Request timeout in milliseconds. Default: 60000 (60s), long enough for a Sync webhook with an AI Node (55s at most). */
     timeoutMs?: number;
 }
 /** A single pipeline execution step received via SSE stream. */
@@ -295,7 +307,13 @@ interface SendResult {
     eventId: string;
     /** Short-lived token for SSE stream auth (returned by ingress, used internally by waitForResult). */
     streamToken?: string;
-    /** Sync/stream: pipeline result status (200=delivered, 422=validation failed, 502=delivery failed, 408=timeout) */
+    /**
+     * Stream (`waitForResult`, `onResult`, `stream()`): pipeline result status —
+     * 200=delivered, 202=paused (approval, merge or a long delay), 422=validation
+     * failed, 500=delivery failed, 408=timeout. A webhook in Sync response mode
+     * answers with the real HTTP status instead: a non-2xx (422, 500, 408) throws
+     * `SendError` with the JSON body in `responseBody`.
+     */
     syncStatus?: number;
     /** Sync/stream: delivery status ('delivered') */
     deliveryStatus?: string;

package/dist/index.d.ts

@@ -16,16 +16,28 @@ interface VerifyOptions {
  *
  * The HMAC is computed as: HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
  *
+ * What is signed: ONLY the timestamp and the raw body. The other
+ * `X-HostWebhook-*` headers (event id, attempt, chain-*) are NOT covered by the
+ * signature: anyone who can reach your endpoint can add or change them. Do not
+ * make security decisions from them. And the timestamp only limits how OLD a
+ * signature may be (`maxAgeSec`); it does not stop the same signed request from
+ * being replayed inside that window. To reject duplicates, remember the event
+ * id of what you already processed.
+ *
  * @param payload - The raw request body (string or Buffer)
  * @param headers - The request headers object
  * @param secret  - Your signing secret (e.g. `whsec_...`)
  * @param options - Optional configuration
- * @throws {VerificationError} If the signature is missing, malformed, expired, or invalid
+ * @throws {VerificationError} If the secret is empty, or the signature is missing, malformed, expired, or invalid
  */
 declare function verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: VerifyOptions): void;
 
 /**
  * Typed representation of HostWebhook delivery headers.
+ *
+ * ⚠️ Only `timestamp` and the body are covered by the signature. The event id,
+ * the attempt number and every `chain*` field come from headers that are NOT
+ * signed: treat them as hints (for example to deduplicate), never as proof.
  */
 interface WebhookHeaders {
     /** Unique event ID (`X-HostWebhook-Event-Id`) */
@@ -220,7 +232,7 @@ interface HostWebhookConfig {
     signature?: StaticSignature;
     /** Custom headers to include in every request. */
     defaultHeaders?: Record<string, string>;
-    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    /** Request timeout in milliseconds. Default: 60000 (60s), long enough for a Sync webhook with an AI Node (55s at most). */
     timeoutMs?: number;
 }
 /** A single pipeline execution step received via SSE stream. */
@@ -295,7 +307,13 @@ interface SendResult {
     eventId: string;
     /** Short-lived token for SSE stream auth (returned by ingress, used internally by waitForResult). */
     streamToken?: string;
-    /** Sync/stream: pipeline result status (200=delivered, 422=validation failed, 502=delivery failed, 408=timeout) */
+    /**
+     * Stream (`waitForResult`, `onResult`, `stream()`): pipeline result status —
+     * 200=delivered, 202=paused (approval, merge or a long delay), 422=validation
+     * failed, 500=delivery failed, 408=timeout. A webhook in Sync response mode
+     * answers with the real HTTP status instead: a non-2xx (422, 500, 408) throws
+     * `SendError` with the JSON body in `responseBody`.
+     */
     syncStatus?: number;
     /** Sync/stream: delivery status ('delivered') */
     deliveryStatus?: string;

package/dist/index.js

@@ -49,7 +49,15 @@ var VerificationError = class extends Error {
     this.name = "VerificationError";
   }
 };
+function exigirUnSecreto(secret) {
+  if (typeof secret !== "string" || secret.trim() === "") {
+    throw new VerificationError(
+      "The signing secret is empty. Set the signing secret of your endpoint (whsec_\u2026) before verifying"
+    );
+  }
+}
 function verify(payload, headers, secret, options) {
+  exigirUnSecreto(secret);
   const sigHeader = getHeader(headers, "x-hostwebhook-signature");
   if (!sigHeader) {
     throw new VerificationError("Missing X-HostWebhook-Signature header");
@@ -159,6 +167,7 @@ function parseHeaders(headers) {
 
 // src/middleware.ts
 function expressMiddleware(secret, options) {
+  exigirUnSecreto(secret);
   return (req, res, next) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -173,6 +182,7 @@ function expressMiddleware(secret, options) {
   };
 }
 function createNestGuard(secret, options) {
+  exigirUnSecreto(secret);
   return class HostWebhookGuard {
     canActivate(context) {
       const req = context.switchToHttp().getRequest();
@@ -182,6 +192,7 @@ function createNestGuard(secret, options) {
   };
 }
 function fastifyHook(secret, options) {
+  exigirUnSecreto(secret);
   return (req, _reply, done) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -213,7 +224,7 @@ var SendError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
-var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_TIMEOUT = 6e4;
 var _apiKey, _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, doSend_fn, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
@@ -410,7 +421,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.6.1"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.6.3"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),
@@ -457,6 +468,10 @@ doSend_fn = async function(token, payload, options) {
     } catch {
       ingressResult = { eventId: text };
     }
+    if (!ingressResult.eventId) {
+      const deCabecera = res.headers.get("x-hostwebhook-event-id");
+      if (deCabecera) ingressResult = { ...ingressResult, eventId: deCabecera };
+    }
   } catch (err) {
     if (err instanceof SendError) throw err;
     if (err instanceof DOMException && err.name === "AbortError") {

package/dist/index.mjs

@@ -15,7 +15,15 @@ var VerificationError = class extends Error {
     this.name = "VerificationError";
   }
 };
+function exigirUnSecreto(secret) {
+  if (typeof secret !== "string" || secret.trim() === "") {
+    throw new VerificationError(
+      "The signing secret is empty. Set the signing secret of your endpoint (whsec_\u2026) before verifying"
+    );
+  }
+}
 function verify(payload, headers, secret, options) {
+  exigirUnSecreto(secret);
   const sigHeader = getHeader(headers, "x-hostwebhook-signature");
   if (!sigHeader) {
     throw new VerificationError("Missing X-HostWebhook-Signature header");
@@ -125,6 +133,7 @@ function parseHeaders(headers) {
 
 // src/middleware.ts
 function expressMiddleware(secret, options) {
+  exigirUnSecreto(secret);
   return (req, res, next) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -139,6 +148,7 @@ function expressMiddleware(secret, options) {
   };
 }
 function createNestGuard(secret, options) {
+  exigirUnSecreto(secret);
   return class HostWebhookGuard {
     canActivate(context) {
       const req = context.switchToHttp().getRequest();
@@ -148,6 +158,7 @@ function createNestGuard(secret, options) {
   };
 }
 function fastifyHook(secret, options) {
+  exigirUnSecreto(secret);
   return (req, _reply, done) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -179,7 +190,7 @@ var SendError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
-var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_TIMEOUT = 6e4;
 var _apiKey, _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, doSend_fn, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
@@ -376,7 +387,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.6.1"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.6.3"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),
@@ -423,6 +434,10 @@ doSend_fn = async function(token, payload, options) {
     } catch {
       ingressResult = { eventId: text };
     }
+    if (!ingressResult.eventId) {
+      const deCabecera = res.headers.get("x-hostwebhook-event-id");
+      if (deCabecera) ingressResult = { ...ingressResult, eventId: deCabecera };
+    }
   } catch (err) {
     if (err instanceof SendError) throw err;
     if (err instanceof DOMException && err.name === "AbortError") {

package/llms.txt

@@ -80,7 +80,7 @@ try {
 ```
 
 verify(payload, headers, secret, options?) — throws VerificationError if invalid.
-VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable replay protection.
+VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable the age check. The signature covers only the timestamp and the raw body: the event-id, attempt and chain-* headers are NOT signed, and the timestamp does not stop a replay inside the window (deduplicate by event id). An empty signing secret is refused.
 
 ## Send Webhooks (sending through HostWebhook)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",