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/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/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/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,
       },
     };

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/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!",