pathao-merchant-sdk 2.1.0 → 2.3.0

package/dist/webhooks.d.ts

@@ -5,35 +5,15 @@ import { EventEmitter } from 'events';
  *
  * Handles incoming webhook events from Pathao.
  *
- * IMPORTANT: The official Pathao API documentation does not describe a webhook
- * specification. This implementation is based on observed webhook behaviour and
- * community research. Treat it as best-effort until Pathao publishes official
- * webhook docs.
- *
- * Signature mechanism: Pathao sends the raw shared secret in the
- * `X-PATHAO-Signature` header. There is no HMAC — the header value IS the
- * secret. A constant-time comparison is used to prevent timing attacks.
- *
- * @example — framework-agnostic
- * ```typescript
- * import {
- *   PathaoWebhookHandler,
- *   PathaoWebhookEvent,
- * } from 'pathao-merchant-sdk/webhooks';
- *
- * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);
- *
- * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
- *   console.log(payload.consignment_id, payload.collected_amount);
- * });
- *
- * // In your HTTP server — raw body as Buffer/string required:
- * const event = handler.process(rawBody, req.headers);
- * res.status(200).json({ received: true });
- * ```
+ * IMPORTANT INTEGRATION DETAILS:
+ * - Pathao does NOT sign incoming requests.
+ * - Instead, Pathao requires you to prove ownership by echoing your webhook secret
+ *   in the \`X-Pathao-Merchant-Webhook-Integration-Secret\` header of EVERY response.
+ * - This SDK automatically handles the \`webhook_integration\` handshake event, which
+ *   expects a 202 status code and the secret header.
  *
  * @example — Express
- * ```typescript
+ * \`\`\`typescript
  * import express from 'express';
  * import {
  *   PathaoWebhookHandler,
@@ -45,13 +25,18 @@ import { EventEmitter } from 'events';
  *
  * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => { ... });
  *
- * // Mount express.raw() BEFORE the webhook middleware
+ * // Mount express.json() BEFORE the webhook middleware
  * app.post(
  *   '/webhooks/pathao',
- *   express.raw({ type: 'application/json' }),
+ *   express.json(),
  *   handler.expressMiddleware(),
+ *   (req, res) => {
+ *     // The middleware already sets the required secret header.
+ *     // You just need to return a 200 OK for standard events.
+ *     res.status(200).send('OK');
+ *   }
  * );
- * ```
+ * \`\`\`
  */
 
 declare class PathaoWebhookError extends Error {
@@ -59,9 +44,10 @@ declare class PathaoWebhookError extends Error {
 }
 /**
  * All webhook event types emitted by Pathao.
- * Values are the exact strings that appear in the `event` field of each payload.
+ * Values are the exact strings that appear in the \`event\` field of each payload.
  */
 declare enum PathaoWebhookEvent {
+    WEBHOOK_INTEGRATION = "webhook_integration",
     ORDER_CREATED = "order.created",
     ORDER_UPDATED = "order.updated",
     ORDER_PICKUP_REQUESTED = "order.pickup-requested",
@@ -81,16 +67,21 @@ declare enum PathaoWebhookEvent {
     ORDER_PAID = "order.paid",
     ORDER_PAID_RETURN = "order.paid-return",
     ORDER_EXCHANGED = "order.exchanged",
+    ORDER_RETURN_ID_CREATED = "order.return-id-created",
+    ORDER_RETURN_IN_TRANSIT = "order.return-in-transit",
+    ORDER_RETURNED_TO_MERCHANT = "order.returned-to-merchant",
     STORE_CREATED = "store.created",
     STORE_UPDATED = "store.updated"
 }
-/** Fields present on every webhook payload */
+interface WebhookIntegrationPayload {
+    event: PathaoWebhookEvent.WEBHOOK_INTEGRATION;
+}
+/** Fields present on every normal webhook payload */
 interface BaseWebhookPayload {
-    /** Dot-notation event type — matches a `PathaoWebhookEvent` value */
     event: string;
-    /** ISO timestamp of when the state change occurred */
+    /** Format: MySQL datetime YYYY-MM-DD HH:MM:SS (no timezone indicator) */
     updated_at: string;
-    /** ISO timestamp of when this webhook was dispatched */
+    /** Format: ISO 8601 timestamp */
     timestamp: string;
 }
 /** Fields shared by all order-related events */
@@ -178,6 +169,25 @@ interface OrderExchangedPayload extends OrderWebhookPayload {
     collected_amount: number;
     reason?: string;
 }
+/** Shared fields for the three return-journey events */
+interface ReturnOrderWebhookPayload extends BaseWebhookPayload {
+    consignment_id: string;
+    return_consignment_id: string;
+    merchant_order_id?: string;
+    store_id: number;
+    collected_amount: number;
+    return_type: 'return' | 'paid-return' | 'exchange' | 'partial-delivery';
+    reason?: string;
+}
+interface OrderReturnIdCreatedPayload extends ReturnOrderWebhookPayload {
+    event: PathaoWebhookEvent.ORDER_RETURN_ID_CREATED;
+}
+interface OrderReturnInTransitPayload extends ReturnOrderWebhookPayload {
+    event: PathaoWebhookEvent.ORDER_RETURN_IN_TRANSIT;
+}
+interface OrderReturnedToMerchantPayload extends ReturnOrderWebhookPayload {
+    event: PathaoWebhookEvent.ORDER_RETURNED_TO_MERCHANT;
+}
 interface StoreCreatedPayload extends StoreWebhookPayload {
     event: PathaoWebhookEvent.STORE_CREATED;
 }
@@ -185,9 +195,10 @@ interface StoreUpdatedPayload extends StoreWebhookPayload {
     event: PathaoWebhookEvent.STORE_UPDATED;
 }
 /** Union of all possible webhook payloads */
-type PathaoWebhookPayload = OrderCreatedPayload | OrderUpdatedPayload | OrderPickupRequestedPayload | OrderAssignedForPickupPayload | OrderPickedPayload | OrderPickupFailedPayload | OrderPickupCancelledPayload | OrderAtSortingHubPayload | OrderInTransitPayload | OrderAtLastMileHubPayload | OrderAssignedForDeliveryPayload | OrderDeliveredPayload | OrderPartialDeliveryPayload | OrderReturnedPayload | OrderDeliveryFailedPayload | OrderOnHoldPayload | OrderPaidPayload | OrderPaidReturnPayload | OrderExchangedPayload | StoreCreatedPayload | StoreUpdatedPayload;
-/** Maps each `PathaoWebhookEvent` to its specific payload type */
+type PathaoWebhookPayload = WebhookIntegrationPayload | OrderCreatedPayload | OrderUpdatedPayload | OrderPickupRequestedPayload | OrderAssignedForPickupPayload | OrderPickedPayload | OrderPickupFailedPayload | OrderPickupCancelledPayload | OrderAtSortingHubPayload | OrderInTransitPayload | OrderAtLastMileHubPayload | OrderAssignedForDeliveryPayload | OrderDeliveredPayload | OrderPartialDeliveryPayload | OrderReturnedPayload | OrderDeliveryFailedPayload | OrderOnHoldPayload | OrderPaidPayload | OrderPaidReturnPayload | OrderExchangedPayload | OrderReturnIdCreatedPayload | OrderReturnInTransitPayload | OrderReturnedToMerchantPayload | StoreCreatedPayload | StoreUpdatedPayload;
+/** Maps each \`PathaoWebhookEvent\` to its specific payload type */
 interface WebhookEventPayloadMap {
+    [PathaoWebhookEvent.WEBHOOK_INTEGRATION]: WebhookIntegrationPayload;
     [PathaoWebhookEvent.ORDER_CREATED]: OrderCreatedPayload;
     [PathaoWebhookEvent.ORDER_UPDATED]: OrderUpdatedPayload;
     [PathaoWebhookEvent.ORDER_PICKUP_REQUESTED]: OrderPickupRequestedPayload;
@@ -207,111 +218,120 @@ interface WebhookEventPayloadMap {
     [PathaoWebhookEvent.ORDER_PAID]: OrderPaidPayload;
     [PathaoWebhookEvent.ORDER_PAID_RETURN]: OrderPaidReturnPayload;
     [PathaoWebhookEvent.ORDER_EXCHANGED]: OrderExchangedPayload;
+    [PathaoWebhookEvent.ORDER_RETURN_ID_CREATED]: OrderReturnIdCreatedPayload;
+    [PathaoWebhookEvent.ORDER_RETURN_IN_TRANSIT]: OrderReturnInTransitPayload;
+    [PathaoWebhookEvent.ORDER_RETURNED_TO_MERCHANT]: OrderReturnedToMerchantPayload;
     [PathaoWebhookEvent.STORE_CREATED]: StoreCreatedPayload;
     [PathaoWebhookEvent.STORE_UPDATED]: StoreUpdatedPayload;
 }
-/** Signature header name sent by Pathao on every webhook request */
-declare const PATHAO_SIGNATURE_HEADER = "x-pathao-signature";
-/**
- * Verify the `X-PATHAO-Signature` header against the configured webhook secret.
- *
- * Uses a constant-time comparison to prevent timing attacks. The header value
- * is the raw shared secret — Pathao does not hash the signature.
- *
- * @returns `true` if valid, `false` if missing or mismatched.
- */
-declare function verifySignature(signature: string | undefined, webhookSecret: string): boolean;
+/** Required response header used to authorize your endpoint with Pathao */
+declare const PATHAO_SECRET_HEADER = "x-pathao-merchant-webhook-integration-secret";
 /**
- * Verify the webhook signature and parse the raw body in one step.
+ * Parses the raw body into a webhook payload.
+ * Pathao does not sign inbound requests, so this just ensures it is valid JSON with an event field.
  *
- * Throws `PathaoWebhookError` on signature failure or malformed JSON.
+ * Throws \`PathaoWebhookError\` on malformed JSON or missing event.
  *
- * @param rawBody       Raw request body — do NOT pre-parse with `JSON.parse`
- * @param headers       Request headers object
- * @param webhookSecret Your Pathao webhook integration secret
+ * @param rawBody       Raw request body or parsed object
  */
-declare function constructEvent(rawBody: Buffer | string, headers: Record<string, string | string[] | undefined>, webhookSecret: string): PathaoWebhookPayload;
-type GenericHeaders = Record<string, string | string[] | undefined>;
+declare function constructEvent(rawBody: Buffer | string | object): PathaoWebhookPayload;
+type WebhookResponseInstructions = {
+    statusCode: number;
+    headers: Record<string, string>;
+    payload: PathaoWebhookPayload | null;
+    error: PathaoWebhookError | null;
+};
 /**
- * Stateful webhook handler that verifies incoming requests, parses payloads,
+ * Stateful webhook handler that parses payloads, provides response instructions,
  * and dispatches events to typed listeners.
  *
  * @example
- * ```typescript
+ * \`\`\`typescript
  * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);
  *
  * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
  *   // payload is fully typed as OrderDeliveredPayload
  *   console.log(payload.consignment_id, payload.collected_amount);
  * });
- * ```
+ * \`\`\`
  */
 declare class PathaoWebhookHandler extends EventEmitter {
     private readonly webhookSecret;
     constructor(webhookSecret: string);
     /** Listen for a specific Pathao event with a fully-typed payload callback. */
     on<E extends PathaoWebhookEvent>(event: E, listener: (payload: WebhookEventPayloadMap[E]) => void): this;
-    /** Fires for every successfully verified event regardless of type. */
+    /** Fires for every successfully parsed event regardless of type. */
     on(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;
-    /** Fires when verification or parsing fails. */
+    /** Fires when parsing fails. */
     on(event: 'error', listener: (error: PathaoWebhookError) => void): this;
+    /** Listen once for a specific Pathao event. */
+    once<E extends PathaoWebhookEvent>(event: E, listener: (payload: WebhookEventPayloadMap[E]) => void): this;
+    once(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;
+    once(event: 'error', listener: (error: PathaoWebhookError) => void): this;
     /**
-     * Verify the signature, parse the body, and dispatch the event.
+     * Parse the body and dispatch the event.
      *
-     * Throws `PathaoWebhookError` on failure and also emits `'error'` so
+     * Throws \`PathaoWebhookError\` on failure and also emits \`'error'\` so
      * listeners can respond without a try/catch.
      *
-     * @param rawBody  Raw request body — must NOT be pre-parsed
-     * @param headers  HTTP request headers
+     * @param rawBody  Raw request body or matched json object
      */
-    process(rawBody: Buffer | string, headers: GenericHeaders): PathaoWebhookPayload;
+    process(rawBody: Buffer | string | object): PathaoWebhookPayload;
     /**
      * Returns an Express-compatible middleware function.
      *
-     * **Requires** `express.raw({ type: 'application/json' })` mounted on the
-     * same route before this middleware so the raw body Buffer is preserved.
-     *
-     * On success the parsed payload is attached to `req.pathaoWebhook`.
-     * On failure a `400` response is returned.
+     * Automatically sets the required \`X-Pathao-Merchant-Webhook-Integration-Secret\` header.
+     * Automatically responds with 202 for the \`webhook_integration\` handshake.
+     * For standard events, attaches the payload to \`req.pathaoWebhook\` and calls \`next()\`.
+     * On error, calls \`next(err)\`.
      *
-     * ```typescript
+     * \`\`\`typescript
      * app.post(
      *   '/webhooks/pathao',
-     *   express.raw({ type: 'application/json' }),
+     *   express.json(),
      *   handler.expressMiddleware(),
+     *   (req, res) => res.sendStatus(200) // You must send 200 for other events
      * );
-     * ```
+     * \`\`\`
      */
     expressMiddleware(): (req: {
-        body: Buffer | string;
-        headers: GenericHeaders;
+        body: Buffer | string | object;
         pathaoWebhook?: PathaoWebhookPayload;
     }, res: {
+        setHeader: (name: string, value: string) => void;
         status: (code: number) => {
-            json: (body: unknown) => void;
+            send: () => void;
         };
     }, next: (err?: unknown) => void) => void;
     /**
-     * Returns a generic async handler for any framework (Fastify, Hono, plain
-     * `http.createServer`, etc.).
+     * Returns response instructions for any framework (Fastify, Hono, etc.).
      *
-     * Never rejects — always resolves with either `{ payload, error: null }` or
-     * `{ payload: null, error: PathaoWebhookError }`.
+     * Never throws — always resolves with a \`WebhookResponseInstructions\` object
+     * that tells you which status code and headers to return, along with the payload/error.
      *
-     * ```typescript
+     * \`\`\`typescript
      * const handle = handler.middleware();
-     * const { payload, error } = await handle(rawBody, request.headers);
-     * if (error) { reply.status(400).send({ error: error.message }); return; }
-     * reply.send({ received: true });
-     * ```
+     * const instructions = await handle(request.body);
+     *
+     * // Apply the required headers (the secret header)
+     * for (const [key, value] of Object.entries(instructions.headers)) {
+     *   reply.header(key, value);
+     * }
+     *
+     * if (instructions.error) {
+     *   return reply.status(instructions.statusCode).send({ error: instructions.error.message });
+     * }
+     *
+     * // If it was the handshake, we should just return 202 as instructed
+     * if (instructions.payload?.event === 'webhook_integration') {
+     *   return reply.status(instructions.statusCode).send();
+     * }
+     *
+     * // Process your real webhook
+     * return reply.status(instructions.statusCode).send({ received: true });
+     * \`\`\`
      */
-    middleware(): (rawBody: Buffer | string, headers: GenericHeaders) => Promise<{
-        payload: PathaoWebhookPayload;
-        error: null;
-    } | {
-        payload: null;
-        error: PathaoWebhookError;
-    }>;
+    middleware(): (rawBody: Buffer | string | object) => Promise<WebhookResponseInstructions>;
 }
 
-export { type BaseWebhookPayload, type OrderAssignedForDeliveryPayload, type OrderAssignedForPickupPayload, type OrderAtLastMileHubPayload, type OrderAtSortingHubPayload, type OrderCreatedPayload, type OrderDeliveredPayload, type OrderDeliveryFailedPayload, type OrderExchangedPayload, type OrderInTransitPayload, type OrderOnHoldPayload, type OrderPaidPayload, type OrderPaidReturnPayload, type OrderPartialDeliveryPayload, type OrderPickedPayload, type OrderPickupCancelledPayload, type OrderPickupFailedPayload, type OrderPickupRequestedPayload, type OrderReturnedPayload, type OrderUpdatedPayload, type OrderWebhookPayload, PATHAO_SIGNATURE_HEADER, PathaoWebhookError, PathaoWebhookEvent, PathaoWebhookHandler, type PathaoWebhookPayload, type StoreCreatedPayload, type StoreUpdatedPayload, type StoreWebhookPayload, type WebhookEventPayloadMap, constructEvent, verifySignature };
+export { type BaseWebhookPayload, type OrderAssignedForDeliveryPayload, type OrderAssignedForPickupPayload, type OrderAtLastMileHubPayload, type OrderAtSortingHubPayload, type OrderCreatedPayload, type OrderDeliveredPayload, type OrderDeliveryFailedPayload, type OrderExchangedPayload, type OrderInTransitPayload, type OrderOnHoldPayload, type OrderPaidPayload, type OrderPaidReturnPayload, type OrderPartialDeliveryPayload, type OrderPickedPayload, type OrderPickupCancelledPayload, type OrderPickupFailedPayload, type OrderPickupRequestedPayload, type OrderReturnIdCreatedPayload, type OrderReturnInTransitPayload, type OrderReturnedPayload, type OrderReturnedToMerchantPayload, type OrderUpdatedPayload, type OrderWebhookPayload, PATHAO_SECRET_HEADER, PathaoWebhookError, PathaoWebhookEvent, PathaoWebhookHandler, type PathaoWebhookPayload, type ReturnOrderWebhookPayload, type StoreCreatedPayload, type StoreUpdatedPayload, type StoreWebhookPayload, type WebhookEventPayloadMap, type WebhookIntegrationPayload, type WebhookResponseInstructions, constructEvent };

package/dist/webhooks.js

@@ -1,6 +1,5 @@
 'use strict';
 
-var crypto = require('crypto');
 var events = require('events');
 
 // src/webhooks.ts
@@ -11,6 +10,7 @@ var PathaoWebhookError = class extends Error {
   }
 };
 var PathaoWebhookEvent = /* @__PURE__ */ ((PathaoWebhookEvent2) => {
+  PathaoWebhookEvent2["WEBHOOK_INTEGRATION"] = "webhook_integration";
   PathaoWebhookEvent2["ORDER_CREATED"] = "order.created";
   PathaoWebhookEvent2["ORDER_UPDATED"] = "order.updated";
   PathaoWebhookEvent2["ORDER_PICKUP_REQUESTED"] = "order.pickup-requested";
@@ -30,44 +30,29 @@ var PathaoWebhookEvent = /* @__PURE__ */ ((PathaoWebhookEvent2) => {
   PathaoWebhookEvent2["ORDER_PAID"] = "order.paid";
   PathaoWebhookEvent2["ORDER_PAID_RETURN"] = "order.paid-return";
   PathaoWebhookEvent2["ORDER_EXCHANGED"] = "order.exchanged";
+  PathaoWebhookEvent2["ORDER_RETURN_ID_CREATED"] = "order.return-id-created";
+  PathaoWebhookEvent2["ORDER_RETURN_IN_TRANSIT"] = "order.return-in-transit";
+  PathaoWebhookEvent2["ORDER_RETURNED_TO_MERCHANT"] = "order.returned-to-merchant";
   PathaoWebhookEvent2["STORE_CREATED"] = "store.created";
   PathaoWebhookEvent2["STORE_UPDATED"] = "store.updated";
   return PathaoWebhookEvent2;
 })(PathaoWebhookEvent || {});
-var PATHAO_SIGNATURE_HEADER = "x-pathao-signature";
-function verifySignature(signature, webhookSecret) {
-  if (!signature || !webhookSecret) return false;
-  try {
-    const sigBuf = Buffer.from(signature, "utf8");
-    const secretBuf = Buffer.from(webhookSecret, "utf8");
-    if (sigBuf.length !== secretBuf.length) return false;
-    return crypto.timingSafeEqual(sigBuf, secretBuf);
-  } catch {
-    return false;
-  }
-}
-function constructEvent(rawBody, headers, webhookSecret) {
-  const signature = extractHeader(headers, PATHAO_SIGNATURE_HEADER);
-  if (!signature) {
-    throw new PathaoWebhookError(
-      `Missing ${PATHAO_SIGNATURE_HEADER} header. Ensure Pathao is sending the signature.`
-    );
-  }
-  if (!verifySignature(signature, webhookSecret)) {
-    throw new PathaoWebhookError(
-      "Invalid webhook signature. Check that your webhookSecret matches the Pathao integration secret."
-    );
-  }
-  const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+var PATHAO_SECRET_HEADER = "x-pathao-merchant-webhook-integration-secret";
+function constructEvent(rawBody) {
   let parsed;
-  try {
-    parsed = JSON.parse(bodyStr);
-  } catch {
-    throw new PathaoWebhookError("Webhook payload is not valid JSON.");
+  if (typeof rawBody === "object" && !Buffer.isBuffer(rawBody)) {
+    parsed = rawBody;
+  } else {
+    const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+    try {
+      parsed = JSON.parse(bodyStr);
+    } catch {
+      throw new PathaoWebhookError("Webhook payload is not valid JSON.");
+    }
   }
   if (!parsed || typeof parsed !== "object" || !("event" in parsed)) {
     throw new PathaoWebhookError(
-      "Webhook payload is missing the required `event` field."
+      "Webhook payload is missing the required 'event' field."
     );
   }
   return parsed;
@@ -86,23 +71,30 @@ var PathaoWebhookHandler = class extends events.EventEmitter {
   on(event, listener) {
     return super.on(event, listener);
   }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  once(event, listener) {
+    return super.once(event, listener);
+  }
   // ─────────────────────────────────────────────────────────────────────────
   /**
-   * Verify the signature, parse the body, and dispatch the event.
+   * Parse the body and dispatch the event.
    *
-   * Throws `PathaoWebhookError` on failure and also emits `'error'` so
+   * Throws \`PathaoWebhookError\` on failure and also emits \`'error'\` so
    * listeners can respond without a try/catch.
    *
-   * @param rawBody  Raw request body — must NOT be pre-parsed
-   * @param headers  HTTP request headers
+   * @param rawBody  Raw request body or matched json object
    */
-  process(rawBody, headers) {
+  process(rawBody) {
     let payload;
     try {
-      payload = constructEvent(rawBody, headers, this.webhookSecret);
+      payload = constructEvent(rawBody);
     } catch (err) {
-      const webhookErr = err instanceof PathaoWebhookError ? err : new PathaoWebhookError(err instanceof Error ? err.message : "Unknown error");
-      this.emit("error", webhookErr);
+      const webhookErr = err instanceof PathaoWebhookError ? err : new PathaoWebhookError(
+        err instanceof Error ? err.message : "Unknown error"
+      );
+      if (this.listenerCount("error") > 0) {
+        this.emit("error", webhookErr);
+      }
       throw webhookErr;
     }
     this.emit(payload.event, payload);
@@ -112,74 +104,95 @@ var PathaoWebhookHandler = class extends events.EventEmitter {
   /**
    * Returns an Express-compatible middleware function.
    *
-   * **Requires** `express.raw({ type: 'application/json' })` mounted on the
-   * same route before this middleware so the raw body Buffer is preserved.
-   *
-   * On success the parsed payload is attached to `req.pathaoWebhook`.
-   * On failure a `400` response is returned.
+   * Automatically sets the required \`X-Pathao-Merchant-Webhook-Integration-Secret\` header.
+   * Automatically responds with 202 for the \`webhook_integration\` handshake.
+   * For standard events, attaches the payload to \`req.pathaoWebhook\` and calls \`next()\`.
+   * On error, calls \`next(err)\`.
    *
-   * ```typescript
+   * \`\`\`typescript
    * app.post(
    *   '/webhooks/pathao',
-   *   express.raw({ type: 'application/json' }),
+   *   express.json(),
    *   handler.expressMiddleware(),
+   *   (req, res) => res.sendStatus(200) // You must send 200 for other events
    * );
-   * ```
+   * \`\`\`
    */
   expressMiddleware() {
     return (req, res, next) => {
       try {
-        req.pathaoWebhook = this.process(req.body, req.headers);
+        res.setHeader(PATHAO_SECRET_HEADER, this.webhookSecret);
+        const payload = this.process(req.body);
+        req.pathaoWebhook = payload;
+        if (payload.event === "webhook_integration" /* WEBHOOK_INTEGRATION */) {
+          res.status(202).send();
+          return;
+        }
         next();
       } catch (err) {
-        res.status(400).json({
-          error: err instanceof Error ? err.message : "Webhook processing failed"
-        });
+        next(err);
       }
     };
   }
   /**
-   * Returns a generic async handler for any framework (Fastify, Hono, plain
-   * `http.createServer`, etc.).
+   * Returns response instructions for any framework (Fastify, Hono, etc.).
    *
-   * Never rejects — always resolves with either `{ payload, error: null }` or
-   * `{ payload: null, error: PathaoWebhookError }`.
+   * Never throws — always resolves with a \`WebhookResponseInstructions\` object
+   * that tells you which status code and headers to return, along with the payload/error.
    *
-   * ```typescript
+   * \`\`\`typescript
    * const handle = handler.middleware();
-   * const { payload, error } = await handle(rawBody, request.headers);
-   * if (error) { reply.status(400).send({ error: error.message }); return; }
-   * reply.send({ received: true });
-   * ```
+   * const instructions = await handle(request.body);
+   *
+   * // Apply the required headers (the secret header)
+   * for (const [key, value] of Object.entries(instructions.headers)) {
+   *   reply.header(key, value);
+   * }
+   *
+   * if (instructions.error) {
+   *   return reply.status(instructions.statusCode).send({ error: instructions.error.message });
+   * }
+   *
+   * // If it was the handshake, we should just return 202 as instructed
+   * if (instructions.payload?.event === 'webhook_integration') {
+   *   return reply.status(instructions.statusCode).send();
+   * }
+   *
+   * // Process your real webhook
+   * return reply.status(instructions.statusCode).send({ received: true });
+   * \`\`\`
    */
   middleware() {
-    return async (rawBody, headers) => {
+    return async (rawBody) => {
+      const headers = { [PATHAO_SECRET_HEADER]: this.webhookSecret };
       try {
-        const payload = this.process(rawBody, headers);
-        return { payload, error: null };
+        const payload = this.process(rawBody);
+        const isHandshake = payload.event === "webhook_integration" /* WEBHOOK_INTEGRATION */;
+        return {
+          statusCode: isHandshake ? 202 : 200,
+          headers,
+          payload,
+          error: null
+        };
       } catch (err) {
         const webhookErr = err instanceof PathaoWebhookError ? err : new PathaoWebhookError(
           err instanceof Error ? err.message : "Unknown error"
         );
-        return { payload: null, error: webhookErr };
+        return {
+          statusCode: 400,
+          headers,
+          payload: null,
+          error: webhookErr
+        };
       }
     };
   }
 };
-function extractHeader(headers, name) {
-  const lower = name.toLowerCase();
-  const key = Object.keys(headers).find((k) => k.toLowerCase() === lower);
-  if (!key) return void 0;
-  const value = headers[key];
-  if (Array.isArray(value)) return value[0];
-  return value;
-}
 
-exports.PATHAO_SIGNATURE_HEADER = PATHAO_SIGNATURE_HEADER;
+exports.PATHAO_SECRET_HEADER = PATHAO_SECRET_HEADER;
 exports.PathaoWebhookError = PathaoWebhookError;
 exports.PathaoWebhookEvent = PathaoWebhookEvent;
 exports.PathaoWebhookHandler = PathaoWebhookHandler;
 exports.constructEvent = constructEvent;
-exports.verifySignature = verifySignature;
 //# sourceMappingURL=webhooks.js.map
 //# sourceMappingURL=webhooks.js.map