IFC-2334: Webhook cache invalidation on KeyValue changes

[polmichel]

Why

When a CoreKeyValue node (used as a webhook header) is created, updated, or deleted, the cached webhook configuration becomes stale. Without invalidation, webhooks continue using outdated header values until the cache naturally expires or the server restarts.

Based on #8590 and #8597.

Closes IFC-2334

What changed

• Cache invalidation flow: New Prefect task (invalidate_webhook_headers) that resolves which webhooks reference a given KeyValue node and clears their cache entries
• Cypher query: KeyValueGetWebhooksQuery traverses webhook__headers relationships to find affected webhooks
• Trigger registration (bug fix): TRIGGER_KEYVALUE_WEBHOOK_INVALIDATE has been added to catalogue.py
• Tests: Unit tests for the invalidation task, component tests for the query + cache integration, functional test verifying end-to-end cache clearing

How to review

Since this PR is based on other PRs, commits to be reviewed start from Encapsulate raw strings into small detectable objects

1. backend/infrahub/webhook/query.py — Cypher query joining KeyValue → Relationship → Webhook
2. backend/infrahub/webhook/tasks/invalidate.py + cache.py — the Prefect flow and cache deletion task
3. backend/infrahub/webhook/triggers.py — trigger definition for KeyValue events
4. Tests: unit/webhook/test_invalidate.py, component/webhook/test_query.py, functional/webhook/test_invalidate.py

How to test

# Unit tests
uv run pytest backend/tests/unit/webhook/test_invalidate.py -v
uv run pytest backend/tests/unit/trigger/test_catalogue.py -v

# Component tests (requires Neo4j)
uv run pytest backend/tests/component/webhook/test_query.py -v

# Functional tests (requires Prefect + Neo4j)
uv run pytest backend/tests/functional/webhook/test_invalidate.py -v

Impact & rollout

• Backward compatibility: No breaking changes
• Performance: Invalidation is event-driven (no polling), scoped to affected webhooks only
• Deployment notes: Should be merged after PRs IFC-2303: CoreKeyValue schema definitions for webhook custom headers #8590 and IFC-2304: Runtime resolution of webhook custom headers #8597

Checklist

• Tests added/updated
• External docs updated (if user-facing or ops-facing change)
• Internal .md docs updated (internal knowledge and AI code tools knowledge)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (4)

• main
• stable
• develop
• release-.*

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: e63bd938-b45d-4ed4-80b6-4fe796b7a350

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

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing pmi-20260312-webhooks-cache-invalidation-mngmt (a7fe5e6) with stable (43d16b8)¹}

Footnotes

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

[polmichel]

While doing the application testing, there is a corner case I am thinking about regarding cache management.

When a KeyValue update fires NodeUpdatedEvent, both webhook-process (if the webhook listens to KeyValue changes) and webhook-invalidate-headers are triggered by the same event. Unless Prefect guarantees ordering between independent automations triggered by the same event, webhook-process could execute before webhook-invalidate-headers and serve stale cached headers.

One possible solution could be to have the webhook-process flow watch to see if the node that triggered the flow is a KeyValue. If so, it could force the data to be retrieved from the database.

This is a hacky solution. I am not sure if the use case I am describing could be a critical issue for customers, i.e. using old headers in the update request of a KeyValue node.

[ogenstad]

While doing the application testing, there is a corner case I am thinking about regarding cache management.

I'm not sure we need to care about that. The way I see it is that we don't guarantee that a config change takes place immediately. A similar situation would be if you create a webhook from the first place and have it trigger on node creation events then we won't fire a webhook for that specific event.

Even with the changes you are making here it could be that we add a header to a webhook and then immediately afterwards we update some other unrelated node. There's a chance that one webhook would fire with the old headers before the new config is applied. I think this is fine as long as the convergence time is short.