docs(webhook): clarify conflict between Authorization header methods

Signed-off-by: 0xsysr3ll <0xsysr3ll@pm.me>

docs/using-seerr/notifications/webhook.md

@@ -22,6 +22,17 @@ This is typically not needed. Please refer to your webhook provider's documentat
 
 This value will be sent as an `Authorization` HTTP header.
 
+### Custom Headers (optional)
+
+You can add additional custom HTTP headers to be sent with each webhook request. This is useful for API keys, custom authentication schemes, or any other headers your webhook endpoint requires.
+
+- Click "Add Header" to add a new header
+- Enter the header name and value
+
+:::warning
+You cannot configure both the **Authorization Header** field and a custom `Authorization` header in Custom Headers at the same time. You must choose one method.
+:::
+
 ### JSON Payload
 
 Customize the JSON payload to suit your needs. Seerr provides several [template variables](#template-variables) for use in the payload, which will be replaced with the relevant data when the notifications are triggered.

server/entity/UserPushSubscription.ts

@@ -1,15 +1,8 @@
 import { DbAwareColumn } from '@server/utils/DbColumnHelper';
-import {
-  Column,
-  Entity,
-  ManyToOne,
-  PrimaryGeneratedColumn,
-  Unique,
-} from 'typeorm';
+import { Column, Entity, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
 import { User } from './User';
 
 @Entity()
-@Unique(['endpoint', 'user'])
 export class UserPushSubscription {
   @PrimaryGeneratedColumn()
   public id: number;

server/lib/notifications/agents/webhook.ts

@@ -196,16 +196,33 @@ class WebhookAgent
     }
 
     try {
+      const headers: Record<string, string> = {};
+
+      if (settings.options.authHeader) {
+        headers.Authorization = settings.options.authHeader;
+      }
+
+      if (
+        settings.options.customHeaders &&
+        settings.options.customHeaders.length > 0
+      ) {
+        settings.options.customHeaders.forEach((header) => {
+          if (header.key && header.value) {
+            // Don't override Authorization header if it's already set via authHeader
+            if (
+              header.key.toLowerCase() !== 'authorization' ||
+              !settings.options.authHeader
+            ) {
+              headers[header.key] = header.value;
+            }
+          }
+        });
+      }
+
       await axios.post(
         webhookUrl,
         this.buildPayload(type, payload),
-        settings.options.authHeader
-          ? {
-              headers: {
-                Authorization: settings.options.authHeader,
-              },
-            }
-          : undefined
+        Object.keys(headers).length > 0 ? { headers } : undefined
       );
 
       return true;

server/lib/notifications/agents/webpush.ts

@@ -24,15 +24,6 @@ interface PushNotificationPayload {
   isAdmin?: boolean;
 }
 
-interface WebPushError extends Error {
-  statusCode?: number;
-  status?: number;
-  body?: string | unknown;
-  response?: {
-    body?: string | unknown;
-  };
-}
-
 class WebPushAgent
   extends BaseAgent<NotificationAgentConfig>
   implements NotificationAgent
@@ -197,30 +188,19 @@ class WebPushAgent
           notificationPayload
         );
       } catch (e) {
-        const webPushError = e as WebPushError;
-        const statusCode = webPushError.statusCode || webPushError.status;
-        const errorMessage = webPushError.message || String(e);
-
-        // RFC 8030: 410/404 are permanent failures, others are transient
-        const isPermanentFailure = statusCode === 410 || statusCode === 404;
-
         logger.error(
-          isPermanentFailure
-            ? 'Error sending web push notification; removing invalid subscription'
-            : 'Error sending web push notification (transient error, keeping subscription)',
+          'Error sending web push notification; removing subscription',
           {
             label: 'Notifications',
             recipient: pushSub.user.displayName,
             type: Notification[type],
             subject: payload.subject,
-            errorMessage,
-            statusCode: statusCode || 'unknown',
+            errorMessage: e.message,
           }
         );
 
-        if (isPermanentFailure) {
-          await userPushSubRepository.remove(pushSub);
-        }
+        // Failed to send notification so we need to remove the subscription
+        userPushSubRepository.remove(pushSub);
       }
     };
 

server/lib/settings/index.ts

@@ -275,6 +275,7 @@ export interface NotificationAgentWebhook extends NotificationAgentConfig {
     webhookUrl: string;
     jsonPayload: string;
     authHeader?: string;
+    customHeaders?: { key: string; value: string }[];
     supportVariables?: boolean;
   };
 }

server/migration/postgres/1765233385034-AddUniqueConstraintToPushSubscription.ts

@@ -1,19 +0,0 @@
-import type { MigrationInterface, QueryRunner } from 'typeorm';
-
-export class AddUniqueConstraintToPushSubscription1765233385034
-  implements MigrationInterface
-{
-  name = 'AddUniqueConstraintToPushSubscription1765233385034';
-
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(
-      `ALTER TABLE "user_push_subscription" ADD CONSTRAINT "UQ_6427d07d9a171a3a1ab87480005" UNIQUE ("endpoint", "userId")`
-    );
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(
-      `ALTER TABLE "user_push_subscription" DROP CONSTRAINT "UQ_6427d07d9a171a3a1ab87480005"`
-    );
-  }
-}

server/migration/sqlite/1765233385034-AddUniqueConstraintToPushSubscription.ts

@@ -1,17 +0,0 @@
-import type { MigrationInterface, QueryRunner } from 'typeorm';
-
-export class AddUniqueConstraintToPushSubscription1765233385034
-  implements MigrationInterface
-{
-  name = 'AddUniqueConstraintToPushSubscription1765233385034';
-
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(
-      `CREATE UNIQUE INDEX "UQ_6427d07d9a171a3a1ab87480005" ON "user_push_subscription" ("endpoint", "userId")`
-    );
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`DROP INDEX "UQ_6427d07d9a171a3a1ab87480005"`);
-  }
-}

server/routes/settings/notifications.ts

@@ -279,6 +279,7 @@ notificationRoutes.get('/webhook', (_req, res) => {
           'utf8'
         )
       ),
+      customHeaders: webhookSettings.options.customHeaders ?? [],
       supportVariables: webhookSettings.options.supportVariables ?? false,
     },
   };
@@ -301,6 +302,7 @@ notificationRoutes.post('/webhook', async (req, res, next) => {
         ),
         webhookUrl: req.body.options.webhookUrl,
         authHeader: req.body.options.authHeader,
+        customHeaders: req.body.options.customHeaders ?? [],
         supportVariables: req.body.options.supportVariables ?? false,
       },
     };
@@ -333,6 +335,7 @@ notificationRoutes.post('/webhook/test', async (req, res, next) => {
         ),
         webhookUrl: req.body.options.webhookUrl,
         authHeader: req.body.options.authHeader,
+        customHeaders: req.body.options.customHeaders ?? [],
         supportVariables: req.body.options.supportVariables ?? false,
       },
     };

server/routes/user/index.ts

@@ -4,7 +4,7 @@ import TautulliAPI from '@server/api/tautulli';
 import { MediaType } from '@server/constants/media';
 import { MediaServerType } from '@server/constants/server';
 import { UserType } from '@server/constants/user';
-import dataSource, { getRepository } from '@server/datasource';
+import { getRepository } from '@server/datasource';
 import Media from '@server/entity/Media';
 import { MediaRequest } from '@server/entity/MediaRequest';
 import { User } from '@server/entity/User';
@@ -25,8 +25,7 @@ import { getHostname } from '@server/utils/getHostname';
 import { Router } from 'express';
 import gravatarUrl from 'gravatar-url';
 import { findIndex, sortBy } from 'lodash';
-import type { EntityManager } from 'typeorm';
-import { In, Not } from 'typeorm';
+import { In } from 'typeorm';
 import userSettingsRoutes from './usersettings';
 
 const router = Router();
@@ -189,82 +188,30 @@ router.post<
   }
 >('/registerPushSubscription', async (req, res, next) => {
   try {
-    // This prevents race conditions where two requests both pass the checks
-    await dataSource.transaction(
-      async (transactionalEntityManager: EntityManager) => {
-        const transactionalRepo =
-          transactionalEntityManager.getRepository(UserPushSubscription);
+    const userPushSubRepository = getRepository(UserPushSubscription);
 
-        // Check for existing subscription by auth or endpoint within transaction
-        const existingSubscription = await transactionalRepo.findOne({
-          relations: { user: true },
-          where: [
-            { auth: req.body.auth, user: { id: req.user?.id } },
-            { endpoint: req.body.endpoint, user: { id: req.user?.id } },
-          ],
-        });
+    const existingSubs = await userPushSubRepository.find({
+      relations: { user: true },
+      where: { auth: req.body.auth, user: { id: req.user?.id } },
+    });
 
-        if (existingSubscription) {
-          // If endpoint matches but auth is different, update with new keys (iOS refresh case)
-          if (
-            existingSubscription.endpoint === req.body.endpoint &&
-            existingSubscription.auth !== req.body.auth
-          ) {
-            existingSubscription.auth = req.body.auth;
-            existingSubscription.p256dh = req.body.p256dh;
-            existingSubscription.userAgent = req.body.userAgent;
+    if (existingSubs.length > 0) {
+      logger.debug(
+        'User push subscription already exists. Skipping registration.',
+        { label: 'API' }
+      );
+      return res.status(204).send();
+    }
 
-            await transactionalRepo.save(existingSubscription);
+    const userPushSubscription = new UserPushSubscription({
+      auth: req.body.auth,
+      endpoint: req.body.endpoint,
+      p256dh: req.body.p256dh,
+      userAgent: req.body.userAgent,
+      user: req.user,
+    });
 
-            logger.debug(
-              'Updated existing push subscription with new keys for same endpoint.',
-              { label: 'API' }
-            );
-            return;
-          }
-
-          logger.debug(
-            'Duplicate subscription detected. Skipping registration.',
-            { label: 'API' }
-          );
-          return;
-        }
-
-        // Clean up old subscriptions from the same device (userAgent) for this user
-        // iOS can silently refresh endpoints, leaving stale subscriptions in the database
-        // Only clean up if we're creating a new subscription (not updating an existing one)
-        if (req.body.userAgent) {
-          const staleSubscriptions = await transactionalRepo.find({
-            relations: { user: true },
-            where: {
-              userAgent: req.body.userAgent,
-              user: { id: req.user?.id },
-              // Only remove subscriptions with different endpoints (stale ones)
-              // Keep subscriptions that might be from different browsers/tabs
-              endpoint: Not(req.body.endpoint),
-            },
-          });
-
-          if (staleSubscriptions.length > 0) {
-            await transactionalRepo.remove(staleSubscriptions);
-            logger.debug(
-              `Removed ${staleSubscriptions.length} stale push subscription(s) from same device.`,
-              { label: 'API' }
-            );
-          }
-        }
-
-        const userPushSubscription = new UserPushSubscription({
-          auth: req.body.auth,
-          endpoint: req.body.endpoint,
-          p256dh: req.body.p256dh,
-          userAgent: req.body.userAgent,
-          user: req.user,
-        });
-
-        await transactionalRepo.save(userPushSubscription);
-      }
-    );
+    userPushSubRepository.save(userPushSubscription);
 
     return res.status(204).send();
   } catch (e) {

src/components/Settings/Notifications/NotificationsWebhook/index.tsx

@@ -5,7 +5,12 @@ import SettingsBadge from '@app/components/Settings/SettingsBadge';
 import globalMessages from '@app/i18n/globalMessages';
 import defineMessages from '@app/utils/defineMessages';
 import { isValidURL } from '@app/utils/urlValidationHelper';
-import { ArrowDownOnSquareIcon, BeakerIcon } from '@heroicons/react/24/outline';
+import {
+  ArrowDownOnSquareIcon,
+  BeakerIcon,
+  PlusIcon,
+  TrashIcon,
+} from '@heroicons/react/24/outline';
 import {
   ArrowPathIcon,
   QuestionMarkCircleIcon,
@@ -80,6 +85,16 @@ const messages = defineMessages(
     supportVariablesTip:
       'Available variables are documented in the webhook template variables section',
     authheader: 'Authorization Header',
+    customHeaders: 'Custom Headers',
+    customHeadersTip:
+      'Add custom HTTP headers to include with webhook requests',
+    customHeadersAdd: 'Add Header',
+    customHeadersRemove: 'Remove',
+    customHeadersKey: 'Header Name',
+    customHeadersValue: 'Header Value',
+    customHeadersIncomplete: 'All headers must have both name and value',
+    customHeadersAuthConflict:
+      'Cannot use both Authorization Header and custom Authorization header. Please remove one.',
     validationJsonPayloadRequired: 'You must provide a valid JSON payload',
     webhooksettingssaved: 'Webhook notification settings saved successfully!',
     webhooksettingsfailed: 'Webhook notification settings failed to save.',
@@ -125,6 +140,43 @@ const NotificationsWebhook = () => {
 
     supportVariables: Yup.boolean(),
 
+    customHeaders: Yup.array()
+      .of(
+        Yup.object().shape({
+          key: Yup.string(),
+          value: Yup.string(),
+        })
+      )
+      .test(
+        'complete-headers',
+        intl.formatMessage(messages.customHeadersIncomplete),
+        function (headers) {
+          if (!headers || headers.length === 0) return true;
+          return headers.every(
+            (header) =>
+              (!header.key || !header.key.trim()) ===
+              (!header.value || !header.value.trim())
+          );
+        }
+      )
+      .test(
+        'auth-conflict',
+        intl.formatMessage(messages.customHeadersAuthConflict),
+        function (headers) {
+          const { authHeader } = this.parent;
+          if (!authHeader || !headers || headers.length === 0) return true;
+
+          const hasCustomAuthHeader = headers.some(
+            (header) =>
+              header.key &&
+              header.value &&
+              header.key.toLowerCase() === 'authorization'
+          );
+
+          return !hasCustomAuthHeader;
+        }
+      ),
+
     jsonPayload: Yup.string()
       .when('enabled', {
         is: true,
@@ -159,6 +211,7 @@ const NotificationsWebhook = () => {
         webhookUrl: data.options.webhookUrl,
         jsonPayload: data.options.jsonPayload,
         authHeader: data.options.authHeader,
+        customHeaders: data.options.customHeaders ?? [],
         supportVariables: data.options.supportVariables ?? false,
       }}
       validationSchema={NotificationsWebhookSchema}
@@ -171,6 +224,9 @@ const NotificationsWebhook = () => {
               webhookUrl: values.webhookUrl,
               jsonPayload: JSON.stringify(values.jsonPayload),
               authHeader: values.authHeader,
+              customHeaders: values.customHeaders.filter(
+                (h: { key: string; value: string }) => h.key && h.value
+              ),
               supportVariables: values.supportVariables,
             },
           });
@@ -229,6 +285,9 @@ const NotificationsWebhook = () => {
                 webhookUrl: values.webhookUrl,
                 jsonPayload: JSON.stringify(values.jsonPayload),
                 authHeader: values.authHeader,
+                customHeaders: values.customHeaders.filter(
+                  (h: { key: string; value: string }) => h.key && h.value
+                ),
                 supportVariables: values.supportVariables ?? false,
               },
             });
@@ -344,6 +403,86 @@ const NotificationsWebhook = () => {
                 </div>
               </div>
             </div>
+            <div className="form-row">
+              <label htmlFor="customHeaders" className="text-label">
+                {intl.formatMessage(messages.customHeaders)}
+                <span className="label-tip">
+                  {intl.formatMessage(messages.customHeadersTip)}
+                </span>
+              </label>
+              <div className="form-input-area">
+                <div className="space-y-2">
+                  {values.customHeaders.map(
+                    (header: { key: string; value: string }, index: number) => (
+                      <div key={index} className="flex gap-2">
+                        <div className="flex-1">
+                          <div className="form-input-field">
+                            <Field
+                              name={`customHeaders.${index}.key`}
+                              type="text"
+                              placeholder={intl.formatMessage(
+                                messages.customHeadersKey
+                              )}
+                            />
+                          </div>
+                        </div>
+                        <div className="flex-1">
+                          <div className="form-input-field">
+                            <Field
+                              name={`customHeaders.${index}.value`}
+                              type="text"
+                              placeholder={intl.formatMessage(
+                                messages.customHeadersValue
+                              )}
+                            />
+                          </div>
+                        </div>
+                        <div className="flex items-center">
+                          <Button
+                            buttonType="danger"
+                            buttonSize="sm"
+                            onClick={(e) => {
+                              e.preventDefault();
+                              const newHeaders = values.customHeaders.filter(
+                                (
+                                  _: { key: string; value: string },
+                                  i: number
+                                ) => i !== index
+                              );
+                              setFieldValue('customHeaders', newHeaders);
+                            }}
+                            title={intl.formatMessage(
+                              messages.customHeadersRemove
+                            )}
+                          >
+                            <TrashIcon />
+                          </Button>
+                        </div>
+                      </div>
+                    )
+                  )}
+                  <Button
+                    buttonType="default"
+                    buttonSize="sm"
+                    onClick={(e) => {
+                      e.preventDefault();
+                      setFieldValue('customHeaders', [
+                        ...values.customHeaders,
+                        { key: '', value: '' },
+                      ]);
+                    }}
+                  >
+                    <PlusIcon />
+                    <span>{intl.formatMessage(messages.customHeadersAdd)}</span>
+                  </Button>
+                </div>
+                {errors.customHeaders &&
+                  touched.customHeaders &&
+                  typeof errors.customHeaders === 'string' && (
+                    <div className="error">{errors.customHeaders}</div>
+                  )}
+              </div>
+            </div>
             <div className="form-row">
               <label htmlFor="webhook-json-payload" className="text-label">
                 {intl.formatMessage(messages.customJson)}

src/components/UserProfile/UserSettings/UserNotificationSettings/UserNotificationsWebPush/index.tsx

@@ -109,28 +109,15 @@ const UserWebPushSettings = () => {
   // Deletes/disables corresponding push subscription from database
   const disablePushNotifications = async (endpoint?: string) => {
     try {
-      const unsubscribedEndpoint = await unsubscribeToPushNotifications(
-        user?.id,
-        endpoint
-      );
+      await unsubscribeToPushNotifications(user?.id, endpoint);
+
+      // Delete from backend if endpoint is available
+      if (subEndpoint) {
+        await deletePushSubscriptionFromBackend(subEndpoint);
+      }
 
       localStorage.setItem('pushNotificationsEnabled', 'false');
       setWebPushEnabled(false);
-
-      // Only delete the current browser's subscription, not all devices
-      const endpointToDelete = unsubscribedEndpoint || subEndpoint || endpoint;
-      if (endpointToDelete) {
-        try {
-          await axios.delete(
-            `/api/v1/user/${user?.id}/pushSubscription/${encodeURIComponent(
-              endpointToDelete
-            )}`
-          );
-        } catch {
-          // Ignore deletion failures - backend cleanup is best effort
-        }
-      }
-
       addToast(intl.formatMessage(messages.webpushhasbeendisabled), {
         autoDismiss: true,
         appearance: 'success',
@@ -170,33 +157,7 @@ const UserWebPushSettings = () => {
   useEffect(() => {
     const verifyWebPush = async () => {
       const enabled = await verifyPushSubscription(user?.id, currentSettings);
-      let isEnabled = enabled;
-
-      if (!enabled && 'serviceWorker' in navigator) {
-        const { subscription } = await getPushSubscription();
-        if (subscription) {
-          isEnabled = true;
-        }
-      }
-
-      if (!isEnabled && dataDevices && dataDevices.length > 0) {
-        const currentUserAgent = navigator.userAgent;
-        const hasMatchingDevice = dataDevices.some(
-          (device) => device.userAgent === currentUserAgent
-        );
-
-        if (hasMatchingDevice) {
-          isEnabled = true;
-        }
-      }
-
-      setWebPushEnabled(isEnabled);
-      if (localStorage.getItem('pushNotificationsEnabled') === null) {
-        localStorage.setItem(
-          'pushNotificationsEnabled',
-          isEnabled ? 'true' : 'false'
-        );
-      }
+      setWebPushEnabled(enabled);
     };
 
     if (user?.id) {

src/i18n/locale/en.json

@@ -681,6 +681,14 @@
   "components.Settings.Notifications.NotificationsSlack.webhookUrlTip": "Create an <WebhookLink>Incoming Webhook</WebhookLink> integration",
   "components.Settings.Notifications.NotificationsWebhook.agentenabled": "Enable Agent",
   "components.Settings.Notifications.NotificationsWebhook.authheader": "Authorization Header",
+  "components.Settings.Notifications.NotificationsWebhook.customHeaders": "Custom Headers",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersAdd": "Add Header",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersAuthConflict": "Cannot use both Authorization Header and custom Authorization header. Please remove one.",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersIncomplete": "All headers must have both name and value",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersKey": "Header Name",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersRemove": "Remove",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersTip": "Add custom HTTP headers to include with webhook requests",
+  "components.Settings.Notifications.NotificationsWebhook.customHeadersValue": "Header Value",
   "components.Settings.Notifications.NotificationsWebhook.customJson": "JSON Payload",
   "components.Settings.Notifications.NotificationsWebhook.resetPayload": "Reset to Default",
   "components.Settings.Notifications.NotificationsWebhook.resetPayloadSuccess": "JSON payload reset successfully!",

src/utils/pushSubscriptionHelpers.ts

@@ -49,17 +49,13 @@ export const verifyPushSubscription = async (
       currentSettings.vapidPublic
     ).toString();
 
-    if (currentServerKey !== expectedServerKey) {
-      return false;
-    }
-
     const endpoint = subscription.endpoint;
 
     const { data } = await axios.get<UserPushSubscription>(
       `/api/v1/user/${userId}/pushSubscription/${encodeURIComponent(endpoint)}`
     );
 
-    return data.endpoint === endpoint;
+    return expectedServerKey === currentServerKey && data.endpoint === endpoint;
   } catch {
     return false;
   }
@@ -69,39 +65,20 @@ export const verifyAndResubscribePushSubscription = async (
   userId: number | undefined,
   currentSettings: PublicSettingsResponse
 ): Promise<boolean> => {
-  if (!userId) {
-    return false;
-  }
-
-  const { subscription } = await getPushSubscription();
   const isValid = await verifyPushSubscription(userId, currentSettings);
 
   if (isValid) {
     return true;
   }
 
-  if (subscription) {
-    return false;
-  }
-
   if (currentSettings.enablePushRegistration) {
     try {
-      const oldEndpoint = await unsubscribeToPushNotifications(userId);
+      // Unsubscribe from the backend to clear the existing push subscription (keys and endpoint)
+      await unsubscribeToPushNotifications(userId);
 
+      // Subscribe again to generate a fresh push subscription with updated keys and endpoint
       await subscribeToPushNotifications(userId, currentSettings);
 
-      if (oldEndpoint) {
-        try {
-          await axios.delete(
-            `/api/v1/user/${userId}/pushSubscription/${encodeURIComponent(
-              oldEndpoint
-            )}`
-          );
-        } catch (error) {
-          // Ignore errors when deleting old endpoint (it might not exist)
-        }
-      }
-
       return true;
     } catch (error) {
       throw new Error(`[SW] Resubscribe failed: ${error.message}`);
@@ -159,26 +136,24 @@ export const subscribeToPushNotifications = async (
 export const unsubscribeToPushNotifications = async (
   userId: number | undefined,
   endpoint?: string
-): Promise<string | null> => {
+) => {
   if (!('serviceWorker' in navigator) || !userId) {
-    return null;
+    return;
   }
 
   try {
     const { subscription } = await getPushSubscription();
 
     if (!subscription) {
-      return null;
+      return false;
     }
 
     const { endpoint: currentEndpoint } = subscription.toJSON();
 
     if (!endpoint || endpoint === currentEndpoint) {
       await subscription.unsubscribe();
-      return currentEndpoint ?? null;
+      return true;
     }
-
-    return null;
   } catch (error) {
     throw new Error(
       `Issue unsubscribing to push notifications: ${error.message}`