feat: trigger FLAG_UPDATED webhooks for v2 versioning environments (#6240)

Author: gagantrivedi

api/environments/models.py

@@ -635,9 +635,9 @@ def generate_webhook_feature_state_data(
         environment: Environment,
         enabled: bool,
         value: typing.Union[str, int, bool, type(None)],  # type: ignore[valid-type]
-        identity_id: typing.Union[int, str] = None,  # type: ignore[assignment]
-        identity_identifier: str = None,  # type: ignore[assignment]
-        feature_segment: FeatureSegment = None,  # type: ignore[assignment]
+        identity_id: int | str | None = None,
+        identity_identifier: str | None = None,
+        feature_segment: FeatureSegment | None = None,
     ) -> dict:  # type: ignore[type-arg]
         if (identity_id or identity_identifier) and not (
             identity_id and identity_identifier

api/features/tasks.py

@@ -90,7 +90,7 @@ def _get_feature_state_webhook_data(feature_state, previous=False):  # type: ign
         enabled=feature_state.enabled,
         value=feature_state_value,
         identity_id=feature_state.identity_id,
-        identity_identifier=getattr(feature_state.identity, "identifier", None),  # type: ignore[arg-type]
+        identity_identifier=getattr(feature_state.identity, "identifier", None),
         feature_segment=feature_state.feature_segment,
     )
 

api/features/versioning/tasks.py

@@ -23,9 +23,12 @@
 )
 from features.versioning.versioning_service import (
     get_environment_flags_queryset,
+    get_updated_feature_states_for_version,
 )
 from users.models import FFAdminUser
-from webhooks.webhooks import WebhookEventType, call_environment_webhooks
+from webhooks import mappers as webhook_mappers
+from webhooks.tasks import call_environment_webhooks, call_organisation_webhooks
+from webhooks.webhooks import WebhookEventType
 
 if typing.TYPE_CHECKING:
     from environments.models import Environment
@@ -131,6 +134,98 @@ def _create_initial_feature_versions(environment: "Environment"):  # type: ignor
         )
 
 
+def _trigger_feature_state_webhooks_for_version(
+    environment_feature_version: EnvironmentFeatureVersion,
+) -> None:
+    """
+    Trigger FLAG_UPDATED webhooks for feature states that have changed in the newly published version.
+
+    This allows webhook consumers to receive granular per-featurestate updates in the same
+    format as non-versioned environments, while NEW_VERSION_PUBLISHED serves as a
+    summary event.
+    """
+    from environments.models import Webhook
+
+    # Get metadata from the version
+    assert environment_feature_version.published_at is not None
+    timestamp = webhook_mappers.datetime_to_webhook_timestamp(
+        environment_feature_version.published_at
+    )
+    changed_by = webhook_mappers.user_or_key_to_changed_by(
+        user=environment_feature_version.published_by,
+        api_key=environment_feature_version.published_by_api_key,
+    )
+
+    changed_feature_states = get_updated_feature_states_for_version(
+        environment_feature_version
+    )
+
+    # Get previous version for retrieving previous states
+    previous_version = environment_feature_version.get_previous_version()
+    previous_feature_states_map = {}
+    if previous_version:
+        for fs in previous_version.feature_states.all():
+            segment_id = fs.feature_segment.segment_id if fs.feature_segment else None
+            key = (fs.identity_id, segment_id)
+            previous_feature_states_map[key] = fs
+
+    # Trigger FLAG_UPDATED webhooks for each changed feature state
+    for feature_state in changed_feature_states:
+        # Get the current state data
+        assert feature_state.environment is not None
+        new_state = Webhook.generate_webhook_feature_state_data(
+            feature_state.feature,
+            environment=feature_state.environment,
+            enabled=feature_state.enabled,
+            value=feature_state.get_feature_state_value(),
+            identity_id=feature_state.identity_id,
+            identity_identifier=getattr(feature_state.identity, "identifier", None),
+            feature_segment=feature_state.feature_segment,
+        )
+
+        # Build webhook data
+        data = {
+            "new_state": new_state,
+            "changed_by": changed_by,
+            "timestamp": timestamp,
+        }
+
+        # Add previous state if it exists
+        segment_id = (
+            feature_state.feature_segment.segment_id
+            if feature_state.feature_segment
+            else None
+        )
+        key = (feature_state.identity_id, segment_id)
+        previous_fs = previous_feature_states_map.get(key)
+
+        if previous_fs:
+            assert previous_fs.environment is not None
+            previous_state = Webhook.generate_webhook_feature_state_data(
+                previous_fs.feature,
+                environment=previous_fs.environment,
+                enabled=previous_fs.enabled,
+                value=previous_fs.get_feature_state_value(),
+                identity_id=previous_fs.identity_id,
+                identity_identifier=getattr(previous_fs.identity, "identifier", None),
+                feature_segment=previous_fs.feature_segment,
+            )
+            data["previous_state"] = previous_state
+
+        # Trigger webhooks
+        call_environment_webhooks(
+            environment_id=environment_feature_version.environment_id,
+            data=data,
+            event_type=WebhookEventType.FLAG_UPDATED.value,
+        )
+
+        call_organisation_webhooks(
+            organisation_id=environment_feature_version.environment.project.organisation_id,
+            data=data,
+            event_type=WebhookEventType.FLAG_UPDATED.value,
+        )
+
+
 @register_task_handler()
 def trigger_update_version_webhooks(environment_feature_version_uuid: str) -> None:
     environment_feature_version = EnvironmentFeatureVersion.objects.get(
@@ -140,6 +235,10 @@ def trigger_update_version_webhooks(environment_feature_version_uuid: str) -> No
         logger.exception("Feature version has not been published.")
         return
 
+    # Trigger FLAG_UPDATED webhooks for any feature states that have changed
+    _trigger_feature_state_webhooks_for_version(environment_feature_version)
+
+    # Then trigger the NEW_VERSION_PUBLISHED webhook as a summary event
     data = environment_feature_version_webhook_schema.dump(environment_feature_version)
     call_environment_webhooks(
         environment_id=environment_feature_version.environment_id,

api/features/versioning/versioning_service.py

@@ -101,6 +101,52 @@ def get_current_live_environment_feature_version(
     )
 
 
+def get_updated_feature_states_for_version(
+    version: EnvironmentFeatureVersion,
+) -> list[FeatureState]:
+    """
+    Returns feature states that changed compared to the previous version.
+    """
+
+    def get_match_key(fs: FeatureState) -> tuple[int | None, int | None]:
+        segment_id = fs.feature_segment.segment_id if fs.feature_segment else None
+        return (fs.identity_id, segment_id)
+
+    def multivariate_values_changed(
+        fs: FeatureState, previous_fs: FeatureState
+    ) -> bool:
+        current_mv_values = {
+            mv.multivariate_feature_option_id: mv.percentage_allocation
+            for mv in fs.multivariate_feature_state_values.all()
+        }
+        previous_mv_values = {
+            mv.multivariate_feature_option_id: mv.percentage_allocation
+            for mv in previous_fs.multivariate_feature_state_values.all()
+        }
+        return current_mv_values != previous_mv_values
+
+    previous_version = version.get_previous_version()
+    previous_feature_states_map = (
+        {get_match_key(fs): fs for fs in previous_version.feature_states.all()}
+        if previous_version
+        else {}
+    )
+
+    changed_feature_states = []
+    for feature_state in version.feature_states.all():
+        previous_fs = previous_feature_states_map.get(get_match_key(feature_state))
+
+        if previous_fs is None or (
+            feature_state.enabled != previous_fs.enabled
+            or feature_state.get_feature_state_value()
+            != previous_fs.get_feature_state_value()
+            or multivariate_values_changed(feature_state, previous_fs)
+        ):
+            changed_feature_states.append(feature_state)
+
+    return changed_feature_states
+
+
 def _get_feature_states_queryset(
     environment: "Environment",
     feature_name: str | None = None,

api/tests/unit/features/versioning/test_unit_versioning_tasks.py

@@ -157,39 +157,136 @@ def test_disable_v2_versioning(
 
 
 @responses.activate
-def test_trigger_update_version_webhooks(
-    environment_v2_versioning: Environment, feature: Feature
+def test_trigger_update_version_webhooks__with_changes(
+    environment_v2_versioning: Environment,
+    feature: Feature,
+    staff_user: FFAdminUser,
 ) -> None:
     # Given
-    version = EnvironmentFeatureVersion.objects.get(
+    v1 = EnvironmentFeatureVersion.objects.get(
         feature=feature, environment=environment_v2_versioning
     )
-    feature_state = version.feature_states.first()
+    v1_fs = v1.feature_states.first()
+
+    v2 = EnvironmentFeatureVersion.objects.create(
+        environment=environment_v2_versioning, feature=feature
+    )
+    v2_fs = v2.feature_states.first()
+    v2_fs.enabled = not v1_fs.enabled  # Make a change
+    v2_fs.save()
+    v2.publish(published_by=staff_user)
 
-    webhook_url = "https://example.com/webhook/"
-    Webhook.objects.create(environment=environment_v2_versioning, url=webhook_url)
+    # Setup webhooks
+    from organisations.models import OrganisationWebhook
 
-    responses.post(url=webhook_url, status=200)
+    environment_webhook_url = "https://example.com/env-webhook/"
+    organisation_webhook_url = "https://example.com/org-webhook/"
+    Webhook.objects.create(
+        environment=environment_v2_versioning, url=environment_webhook_url, enabled=True
+    )
+    OrganisationWebhook.objects.create(
+        organisation=environment_v2_versioning.project.organisation,
+        name="Test Org Webhook",
+        url=organisation_webhook_url,
+        enabled=True,
+    )
+    responses.post(url=environment_webhook_url, status=200)
+    responses.post(url=organisation_webhook_url, status=200)
 
     # When
-    trigger_update_version_webhooks(str(version.uuid))
+    trigger_update_version_webhooks(str(v2.uuid))
 
     # Then
-    assert len(responses.calls) == 1
-    assert responses.calls[0].request.url == webhook_url  # type: ignore[union-attr]
-    assert json.loads(responses.calls[0].request.body) == {  # type: ignore[union-attr]
+    # Should trigger 3 webhook calls: 2 environment (FLAG_UPDATED + NEW_VERSION_PUBLISHED)
+    # and 1 organisation (FLAG_UPDATED only)
+    assert len(responses.calls) == 3
+
+    # Verify FLAG_UPDATED webhook to environment (first call)
+    flag_updated_env_body = json.loads(responses.calls[0].request.body)  # type: ignore[union-attr]
+    assert flag_updated_env_body["event_type"] == WebhookEventType.FLAG_UPDATED.name
+    assert flag_updated_env_body["data"]["new_state"]["enabled"] == v2_fs.enabled
+    assert flag_updated_env_body["data"]["new_state"]["feature"]["id"] == feature.id
+    assert flag_updated_env_body["data"]["new_state"]["feature"]["name"] == feature.name
+    assert (
+        flag_updated_env_body["data"]["new_state"]["feature_state_value"]
+        == v2_fs.get_feature_state_value()
+    )
+    assert flag_updated_env_body["data"]["previous_state"]["enabled"] == v1_fs.enabled
+    assert (
+        flag_updated_env_body["data"]["previous_state"]["feature_state_value"]
+        == v1_fs.get_feature_state_value()
+    )
+    assert flag_updated_env_body["data"]["changed_by"] == staff_user.email
+    assert "timestamp" in flag_updated_env_body["data"]
+
+    # Verify FLAG_UPDATED webhook to organisation (second call)
+    flag_updated_org_body = json.loads(responses.calls[1].request.body)  # type: ignore[union-attr]
+    assert flag_updated_org_body == flag_updated_env_body  # Should be identical
+
+    # Verify NEW_VERSION_PUBLISHED webhook to environment (third call)
+    new_version_body = json.loads(responses.calls[2].request.body)  # type: ignore[union-attr]
+    assert new_version_body == {
+        "event_type": WebhookEventType.NEW_VERSION_PUBLISHED.name,
         "data": {
-            "uuid": str(version.uuid),
+            "uuid": str(v2.uuid),
             "feature": {"id": feature.id, "name": feature.name},
-            "published_by": None,
+            "published_by": {"id": staff_user.id, "email": staff_user.email},
             "feature_states": [
                 {
-                    "enabled": feature_state.enabled,
-                    "value": feature_state.get_feature_state_value(),
+                    "enabled": v2_fs.enabled,
+                    "value": v2_fs.get_feature_state_value(),
                 }
             ],
         },
+    }
+
+
+@responses.activate
+def test_trigger_update_version_webhooks__without_changes(
+    environment_v2_versioning: Environment,
+    feature: Feature,
+    staff_user: FFAdminUser,
+) -> None:
+    # Given
+    v1 = EnvironmentFeatureVersion.objects.get(
+        feature=feature, environment=environment_v2_versioning
+    )
+    v1.publish(published_by=staff_user)
+
+    v2 = EnvironmentFeatureVersion.objects.create(
+        environment=environment_v2_versioning, feature=feature
+    )
+    v2.publish(published_by=staff_user)
+
+    # Setup webhook
+    environment_webhook_url = "https://example.com/env-webhook/"
+    Webhook.objects.create(
+        environment=environment_v2_versioning, url=environment_webhook_url, enabled=True
+    )
+    responses.post(url=environment_webhook_url, status=200)
+
+    # When
+    trigger_update_version_webhooks(str(v2.uuid))
+
+    # Then
+    # Should trigger only 1 webhook call: NEW_VERSION_PUBLISHED (no FLAG_UPDATED since no changes)
+    assert len(responses.calls) == 1
+
+    # Verify NEW_VERSION_PUBLISHED webhook data
+    new_version_body = json.loads(responses.calls[0].request.body)  # type: ignore[union-attr]
+    assert new_version_body == {
         "event_type": WebhookEventType.NEW_VERSION_PUBLISHED.name,
+        "data": {
+            "uuid": str(v2.uuid),
+            "feature": {"id": feature.id, "name": feature.name},
+            "published_by": {"id": staff_user.id, "email": staff_user.email},
+            "feature_states": [
+                {
+                    "enabled": v2.feature_states.first().enabled,
+                    "value": v2.feature_states.first().get_feature_state_value(),
+                }
+            ],
+        },
     }