Merge pull request #468 from zerosumsum/feature/434-webhook-custom-headers

feat: support custom configured headers for webhook delivery

Author: emdevelopa

backend/migrations/20260328000002_add_webhook_custom_headers.js

@@ -0,0 +1,25 @@
+/**
+ * Migration: add webhook_custom_headers column to merchants
+ *
+ * Stores an optional JSON object of extra HTTP headers that should be
+ * forwarded with every webhook POST for this merchant, e.g.
+ *   { "X-My-Auth": "token123", "X-Source": "stellar-pay" }
+ *
+ * Header names are restricted to safe ASCII characters; values must be
+ * non-empty strings.  Validation is enforced at the application layer.
+ */
+export async function up(knex) {
+  await knex.schema.alterTable("merchants", (table) => {
+    table
+      .jsonb("webhook_custom_headers")
+      .nullable()
+      .defaultTo(null)
+      .comment("Merchant-defined extra headers merged into webhook POSTs");
+  });
+}
+
+export async function down(knex) {
+  await knex.schema.alterTable("merchants", (table) => {
+    table.dropColumn("webhook_custom_headers");
+  });
+}

backend/src/lib/request-schemas.js

@@ -213,6 +213,8 @@ export const paymentSessionZodSchema = paymentBaseSchema
 
 export const v2PaymentSessionSchema = paymentSessionZodSchema;
 
+const SAFE_HEADER_NAME_RE = /^[a-zA-Z0-9\-_]+$/;
+
 export const webhookSettingsSchema = z.object({
   webhook_url: z.preprocess(
     (value) => {
@@ -229,6 +231,14 @@ export const webhookSettingsSchema = z.object({
       .refine((val) => val.startsWith("https://"), "webhook_url must use HTTPS")
       .optional(),
   ),
+  custom_headers: z
+    .record(z.string(), z.string().min(1, "Header value must not be empty"))
+    .refine(
+      (obj) => Object.keys(obj).every((k) => SAFE_HEADER_NAME_RE.test(k)),
+      "Header names must contain only alphanumeric characters, hyphens, or underscores",
+    )
+    .optional()
+    .nullable(),
 });
 
 

backend/src/lib/webhooks.js

@@ -181,16 +181,55 @@ function scheduleRetries(url, payload, headers, paymentId) {
   setTimeout(retry, RETRY_DELAYS_MS[0]);
 }
 
+/**
+ * Validate and sanitise a merchant-supplied custom headers object.
+ *
+ * Accepted: plain object whose keys are safe ASCII header names and whose
+ * values are non-empty strings.
+ * Reserved system headers (Content-Type, User-Agent, Stellar-Signature) are
+ * silently dropped to prevent merchants from overriding security controls.
+ *
+ * @param {unknown} raw  The value stored in merchants.webhook_custom_headers.
+ * @returns {Record<string, string>} A safe subset of the supplied headers.
+ */
+export function sanitizeCustomHeaders(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+
+  const SAFE_HEADER_NAME = /^[a-zA-Z0-9\-_]+$/;
+  const RESERVED = new Set([
+    "content-type",
+    "user-agent",
+    "stellar-signature",
+  ]);
+
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!SAFE_HEADER_NAME.test(key)) continue;
+    if (RESERVED.has(key.toLowerCase())) continue;
+    if (typeof value !== "string" || value.trim() === "") continue;
+    result[key] = value;
+  }
+  return result;
+}
+
 /**
  * Sends a signed webhook POST request to `url`.
+ *
+ * @param {string}  url           Destination URL.
+ * @param {object}  payload       JSON body to send.
+ * @param {string}  secret        HMAC signing secret.
+ * @param {string|null} paymentId For delivery logging.
+ * @param {object}  [customHeaders={}] Merchant-defined extra headers.
  */
-export async function sendWebhook(url, payload, secret, paymentId = null) {
+export async function sendWebhook(url, payload, secret, paymentId = null, customHeaders = {}) {
   if (!url) return { ok: false, skipped: true };
 
   const signingSecret = secret || process.env.WEBHOOK_SECRET || "";
   const rawBody = JSON.stringify(payload);
 
   const headers = {
+    // Merchant custom headers first so system headers always take precedence.
+    ...sanitizeCustomHeaders(customHeaders),
     "Content-Type": "application/json",
     "User-Agent": "stellar-payment-api/0.1"
   };

backend/src/routes/merchants.js

@@ -511,19 +511,27 @@ function createMerchantsRouter({
       try {
         const body = req.body;
 
+        const updatePayload = { webhook_url: body.webhook_url || null };
+        if ("custom_headers" in body) {
+          updatePayload.webhook_custom_headers = body.custom_headers ?? null;
+        }
+
         const { data, error } = await supabase
           .from("merchants")
-          .update({ webhook_url: body.webhook_url || null })
+          .update(updatePayload)
           .eq("id", req.merchant.id)
-          .select("webhook_url")
+          .select("webhook_url, webhook_custom_headers")
           .single();
 
         if (error) {
           error.status = 500;
           throw error;
         }
 
-        res.json({ webhook_url: data.webhook_url || "" });
+        res.json({
+          webhook_url: data.webhook_url || "",
+          custom_headers: data.webhook_custom_headers ?? {},
+        });
       } catch (err) {
         next(err);
       }

backend/src/routes/payments.js

@@ -388,7 +388,7 @@ function createPaymentsRouter({
         let query = supabase
           .from("payments")
           .select(
-            "id, merchant_id, amount, asset, asset_issuer, recipient, status, tx_id, memo, memo_type, webhook_url, merchants(webhook_secret, webhook_version, notification_email, email)"
+            "id, merchant_id, amount, asset, asset_issuer, recipient, status, tx_id, memo, memo_type, webhook_url, merchants(webhook_secret, webhook_version, webhook_custom_headers, notification_email, email)"
           );
 
         if (req.merchant?.id) {
@@ -494,7 +494,9 @@ function createPaymentsRouter({
         const webhookResult = await sendWebhook(
           data.webhook_url,
           webhookPayload,
-          merchantSecret
+          merchantSecret,
+          data.id,
+          data.merchants?.webhook_custom_headers ?? {}
         );
 
         if (!webhookResult.ok && !webhookResult.skipped) {

backend/tests/integration/webhook-custom-headers.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi } from "vitest";
+
+// Stub Supabase before importing webhooks so the missing-env-var guard doesn't fire.
+vi.mock("../../src/lib/supabase.js", () => ({ supabase: {} }));
+
+import { sanitizeCustomHeaders } from "../../src/lib/webhooks.js";
+
+describe("sanitizeCustomHeaders", () => {
+  it("returns empty object for null/undefined input", () => {
+    expect(sanitizeCustomHeaders(null)).toEqual({});
+    expect(sanitizeCustomHeaders(undefined)).toEqual({});
+  });
+
+  it("returns empty object for non-object input", () => {
+    expect(sanitizeCustomHeaders("string")).toEqual({});
+    expect(sanitizeCustomHeaders([])).toEqual({});
+    expect(sanitizeCustomHeaders(42)).toEqual({});
+  });
+
+  it("passes through valid headers", () => {
+    const result = sanitizeCustomHeaders({
+      "X-My-Auth": "token123",
+      "X-Source": "stellar-pay",
+    });
+    expect(result["X-My-Auth"]).toBe("token123");
+    expect(result["X-Source"]).toBe("stellar-pay");
+  });
+
+  it("drops headers with unsafe names", () => {
+    const result = sanitizeCustomHeaders({
+      "X-Valid": "ok",
+      "Bad Header!": "should-drop",
+      "Also Bad<>": "drop",
+    });
+    expect(Object.keys(result)).toEqual(["X-Valid"]);
+  });
+
+  it("drops reserved system headers regardless of case", () => {
+    const result = sanitizeCustomHeaders({
+      "content-type": "text/plain",
+      "User-Agent": "hacker",
+      "STELLAR-SIGNATURE": "fake",
+      "X-Custom": "keep",
+    });
+    expect(result).toEqual({ "X-Custom": "keep" });
+  });
+
+  it("drops headers with empty string values", () => {
+    const result = sanitizeCustomHeaders({
+      "X-Empty": "",
+      "X-Keep": "value",
+    });
+    expect(result).toEqual({ "X-Keep": "value" });
+  });
+
+  it("drops headers with non-string values", () => {
+    const result = sanitizeCustomHeaders({
+      "X-Number": 123,
+      "X-Bool": true,
+      "X-String": "ok",
+    });
+    expect(result).toEqual({ "X-String": "ok" });
+  });
+});