(spec-kit-only POC) INFP-445: Custom HTTP headers for webhooks

[polmichel]

POC: spec-kit only approach — This feature was implemented entirely using the spec-kit workflow (specify, plan, tasks, implement) to evaluate the methodology on a real feature.

This PR has been initially done based on spec-kitty adaptation commits #8576

Why

Webhooks currently have no way to include custom HTTP headers, which are required for authentication tokens, API keys, and routing metadata when integrating with external systems.

Goal: Allow users to attach typed key-value headers (static, password, environment variable) to any webhook.

Non-goal: Header value resolution at send time (environment variable lookup) is not yet implemented — this PR adds the schema, storage, and configuration plumbing.

Closes INFP-445

What changed

• New CoreKeyValue generic + 3 node types (CoreKeyValueStatic, CoreKeyValuePassword, CoreKeyValueEnvironmentVariable) in backend/infrahub/core/schema/definitions/core/key_value.py
• headers relationship added to CoreWebhook generic — all webhook types inherit it
• Webhook configure/process flows updated to load and inject headers when firing webhooks
• Trigger catalogue extended with WEBHOOK_CONFIGURE event for header changes
• Unit, functional, integration, and E2E tests covering header CRUD, webhook attachment, and header injection
• Documentation updated: guides and topics pages for webhook headers
• Spec-kit artifacts in dev/specs/infp-445-webhook-headers/ (spec, plan, tasks, research, contracts)

How to review

1. Start with the schema: backend/infrahub/core/schema/definitions/core/key_value.py and webhook.py
2. Then the webhook flow changes: webhook/models.py, webhook/tasks/configure.py, webhook/tasks/process.py
3. Tests: test_webhook_headers.py (functional), test_models.py (unit), webhook.spec.ts (E2E)
4. dev/specs/ artifacts are the spec-kit output — review for process quality, not code

How to test

uv run invoke backend.test-unit
uv run pytest backend/tests/functional/webhook/test_webhook_headers.py -v
cd frontend/app && npx playwright test tests/e2e/webhook/webhook.spec.ts

Impact & rollout

• Backward compatibility: Additive only — new schema nodes + new relationship on existing webhook generic. No breaking changes.
• Performance: Minimal — one additional relationship traversal per webhook fire.
• Deployment notes: Safe to deploy. New schema nodes auto-created on migration.

Checklist

• Tests added/updated
• Changelog entry added
• External docs updated
• Internal .md docs updated
• [] I have reviewed AI generated content

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dade481e-4dae-49ab-b98a-7133b60ab0e4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[polmichel]

I will use this PR, which has been 100% AI-generated, to compare with another one that I will create using Spec-Kitty for a more targeted and human-driven development approach. Comparing both could lead us to highlight missing pieces we have in internal documentation.

[codspeed-hq]

Merging this PR will improve performance by 38.69%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 12 improved benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_schemabranch_process	1,026 ms	828.4 ms	+23.85%
⚡	test_graphql_generate_schema	515.9 ms	372 ms	+38.69%
⚡	test_schemabranch_duplicate	7.2 ms	5.9 ms	+22.81%
⚡	test_query_rel_many	693 ms	522.9 ms	+32.53%
⚡	test_query_rel_one	662.7 ms	500 ms	+32.54%
⚡	test_get_menu	245.7 ms	188.7 ms	+30.17%
⚡	test_load_node_to_db_node_schema	66.2 ms	52.1 ms	+27.12%
⚡	test_query_one_model	464.7 ms	352.6 ms	+31.78%
⚡	test_base_schema_duplicate_CoreProposedChange	2.1 ms	1.7 ms	+27.76%
⚡	test_nodemanager_querypeers	1.5 ms	1.2 ms	+21.96%
⚡	test_relationshipmanager_getpeer	155.7 µs	130.9 µs	+18.89%
⚡	test_get_schema	323.8 ms	261.2 ms	+23.99%

---

_{Comparing pmi-445-webhook-headers (be4e3ad) with stable (8919be6)¹}

Footnotes

1. No successful run was found on pmi-20260227-webhooks-ifc-2272 (a29379b) during the generation of this report, so stable (8919be6) was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[ogenstad]

@polmichel, I think we can get rid of this branch now?