feat(notifications): webhook custom headers

[0xSysR3ll]

Description

This PR adds the ability to configure custom HTTP headers for webhook notifications.

• Supersedes feat(webhook): add API key support for webhook notifications #1948

How Has This Been Tested?

• Added custom headers via the UI and verified they appear in webhook requests
• Tested adding/removing multiple headers
• Verified empty headers are automatically filtered out on save
• Confirmed Authorization header (authHeader ) takes precedence over custom Authorization headers
• Tested webhook test notification with custom headers (used a simple python webhook listener script to inspect headers sent in requests)

Screenshots / Logs (if applicable)

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract
• Database migration (if required)

Summary by CodeRabbit

Release Notes

• New Features

  • Webhook notifications now support custom HTTP headers with an intuitive add/remove interface for configuring header key-value pairs
  • Built-in validation prevents simultaneous use of Authorization and custom Authorization headers
  • Custom headers included in webhook test payloads for verification

• Documentation

  • Webhook notification guide updated with Custom Headers configuration details

[M0NsTeRRR]

Confirmed Authorization header (authHeader ) takes precedence over custom Authorization headers

In my opinion, it would be better to prevent saving if the system detects that authentication headers are already configured.

[0xSysR3ll]

Confirmed Authorization header (authHeader ) takes precedence over custom Authorization headers

In my opinion, it would be better to prevent saving if the system detects that authentication headers are already configured.

Mmm not a bad idea ! I'll add this :)

[M0NsTeRRR]

is this ready for review @0xSysR3ll ? you didn't request a new review in case of

[0xSysR3ll]

is this ready for review @0xSysR3ll ? you didn't request a new review in case of

Ye my bad ! Forgot to.

[gauthier-th]

LGTM!

[Copilot]

Pull request overview

Adds support for configuring and sending custom HTTP headers with webhook notification requests, spanning UI, API persistence, agent send behavior, and documentation.

Changes:

• Adds a Custom Headers editor to the webhook notification settings UI (with basic validation and save/test wiring).
• Persists customHeaders through the webhook settings API and types it in server settings.
• Applies configured headers (with authHeader precedence) when sending webhook requests; documents the new option.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/i18n/locale/en.json	Adds UI strings for custom webhook headers.
src/components/Settings/Notifications/NotificationsWebhook/index.tsx	UI to add/remove headers; client-side validation; includes headers in save/test payloads.
server/routes/settings/notifications.ts	Reads/writes customHeaders for webhook settings and test endpoint payloads.
server/lib/settings/index.ts	Extends webhook agent settings type to include customHeaders.
server/lib/notifications/agents/webhook.ts	Builds Axios headers config from authHeader + customHeaders with auth precedence.
docs/using-seerr/notifications/webhook.md	Documents the custom headers feature and the Authorization conflict rule.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

Webhook notifications now support custom HTTP headers. The feature spans backend header propagation, API configuration routes, frontend UI for header management, settings schema updates, documentation, and internationalization strings for UI labels and validations.

Changes

Cohort / File(s)	Summary
Documentation docs/using-seerr/notifications/webhook.md	Added "Custom Headers (optional)" section explaining header configuration and warning against simultaneous Authorization header usage.
Backend Webhook Handler server/lib/notifications/agents/webhook.ts	Refactored header handling to consolidate authHeader and customHeaders into a unified headers object; includes conditional logic to avoid conflicts between separate Authorization header and custom Authorization.
Settings Schema & Routes server/lib/settings/index.ts, server/routes/settings/notifications.ts	Added optional customHeaders field to NotificationAgentWebhook configuration; propagated through GET/POST webhook endpoints with default empty array values.
Frontend UI & Validation src/components/Settings/Notifications/NotificationsWebhook/index.tsx	Implemented custom header row UI (key/value pairs) with add/remove functionality, value trimming, incomplete header filtering, and conflict validation preventing simultaneous authHeader and custom Authorization header usage.
Internationalization src/i18n/locale/en.json	Added eight translation keys for custom header labels, descriptions, validation messages, and action buttons.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

Hop skip and a header's way,
Custom fields now come to play,
Webhooks dancing, custom dressed,
Authorization? Conflict's best.
Rabbit's code, now manifest! 🐰

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(notifications): webhook custom headers' clearly and specifically describes the main change: adding custom headers functionality to webhook notifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/components/Settings/Notifications/NotificationsWebhook/index.tsx (1)

227-235: Deduplicate custom-header normalization before request payload creation.

The same trim/filter pipeline appears in both save and test paths; extract it once to keep behavior consistent.

♻️ Suggested refactor

+  const normalizeCustomHeaders = (headers: { key: string; value: string }[] = []) =>
+    headers
+      .map((h) => ({
+        key: h.key?.trim() ?? '',
+        value: h.value?.trim() ?? '',
+      }))
+      .filter((h) => h.key.length > 0 && h.value.length > 0);

       onSubmit={async (values) => {
         try {
           await axios.post('/api/v1/settings/notifications/webhook', {
@@
               authHeader: values.authHeader,
-              customHeaders: (values.customHeaders ?? [])
-                .map((h: { key: string; value: string }) => ({
-                  key: h.key?.trim() ?? '',
-                  value: h.value?.trim() ?? '',
-                }))
-                .filter(
-                  (h: { key: string; value: string }) =>
-                    h.key.length > 0 && h.value.length > 0
-                ),
+              customHeaders: normalizeCustomHeaders(values.customHeaders ?? []),
               supportVariables: values.supportVariables,
             },
           });
@@
                 webhookUrl: values.webhookUrl,
                 jsonPayload: JSON.stringify(values.jsonPayload),
                 authHeader: values.authHeader,
-                customHeaders: (values.customHeaders ?? [])
-                  .map((h: { key: string; value: string }) => ({
-                    key: h.key?.trim() ?? '',
-                    value: h.value?.trim() ?? '',
-                  }))
-                  .filter(
-                    (h: { key: string; value: string }) =>
-                      h.key.length > 0 && h.value.length > 0
-                  ),
+                customHeaders: normalizeCustomHeaders(values.customHeaders ?? []),
                 supportVariables: values.supportVariables ?? false,
               },
             });

Also applies to: 294-302

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/Settings/Notifications/NotificationsWebhook/index.tsx` around
lines 227 - 235, The custom header trimming/filtering logic is duplicated in
both the save and test request paths; extract it into a single helper (e.g.,
normalizeCustomHeaders) that accepts the raw values.customHeaders and returns
the trimmed-and-filtered array, then replace the inline map/filter blocks used
when building the request payloads (the customHeaders fields in both the save
and test flows) with calls to that helper so both paths share identical
normalization logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@server/routes/settings/notifications.ts`:
- Around line 305-306: The incoming req.body.options.customHeaders must be
validated and normalized before use: add a small helper (e.g.,
normalizeCustomHeaders or validateCustomHeaders) called where customHeaders and
supportVariables are read to ensure the value is an array, coerce each item to
an object with string key/value, trim both, drop entries with empty keys/values,
deduplicate by key, and return [] for invalid input; additionally check for an
Authorization header conflict (reject/save error if any header key equals
"authorization" or conflicts with existing auth configuration) and only persist
the sanitized array in place of req.body.options.customHeaders and
supportVariables.

In `@src/components/Settings/Notifications/NotificationsWebhook/index.tsx`:
- Around line 453-471: The remove-header icon Button (the Button wrapping
<TrashIcon /> in the customHeaders list) lacks an explicit accessible name;
update that Button to include an aria-label (or aria-labelledby) using the
localized string (e.g., intl.formatMessage(messages.customHeadersRemove)) so
screen readers announce its purpose, while keeping the existing onClick handler
that computes newHeaders and calls setFieldValue('customHeaders', newHeaders);
ensure the aria-label text matches the visible intent of the button.

---

Nitpick comments:
In `@src/components/Settings/Notifications/NotificationsWebhook/index.tsx`:
- Around line 227-235: The custom header trimming/filtering logic is duplicated
in both the save and test request paths; extract it into a single helper (e.g.,
normalizeCustomHeaders) that accepts the raw values.customHeaders and returns
the trimmed-and-filtered array, then replace the inline map/filter blocks used
when building the request payloads (the customHeaders fields in both the save
and test flows) with calls to that helper so both paths share identical
normalization logic.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a16d046 and faac58d.

📒 Files selected for processing (6)

• docs/using-seerr/notifications/webhook.md
• server/lib/notifications/agents/webhook.ts
• server/lib/settings/index.ts
• server/routes/settings/notifications.ts
• src/components/Settings/Notifications/NotificationsWebhook/index.tsx
• src/i18n/locale/en.json

[gauthier-th]

LGTM