From 59f1ac790de01a465e9b708c18a6a17425408210 Mon Sep 17 00:00:00 2001 From: IKarbowiak Date: Fri, 28 Nov 2025 13:14:17 +0100 Subject: [PATCH] Add update webhook behavior unification --- ...004_update_webhook_behavior_unification.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 decisions/004_update_webhook_behavior_unification.md diff --git a/decisions/004_update_webhook_behavior_unification.md b/decisions/004_update_webhook_behavior_unification.md new file mode 100644 index 0000000..1c54b7a --- /dev/null +++ b/decisions/004_update_webhook_behavior_unification.md @@ -0,0 +1,30 @@ +# Update Webhook Emission Unification + +Status: accepted + +Summary: The `Update` webhook should be sent only for non-metadata changes on an instance, while the `MetadataUpdate>` webhook should be sent exclusively for metadata changes. This change aims to reduce redundant webhook events and improve clarity. + +## Issue + +Currently, the `Update` webhook is triggered even for metadata-only changes. This behavior leads to unnecessary webhook events, causing confusion and inefficiencies for clients relying on these events to track meaningful changes. + +## Assumptions + +- Clients use `Update` webhooks to track significant changes to entities. +- Metadata changes are often automated and do not require the same level of attention as other updates. +- Backward compatibility is critical for existing integrations. + +## Constraints + +- The solution must ensure backward compatibility to avoid breaking existing client implementations. +- The implementation should minimize performance overhead when determining the type of change. + +## Background + +Clients have reported that metadata updates generate hundreds of redundant `Update` webhook events daily. These events do not reflect actual changes to the entity itself, leading to inefficiencies and unnecessary processing on the client side. + +## Future State + +Starting from version 3.22, the `Update` webhook will only be triggered for actual changes to the entity, excluding metadata changes. Metadata changes will trigger the `MetadataUpdate>` webhook instead. This behavior will be controlled by an instance tracker to determine the type of change. + +To ensure backward compatibility, a flag will be introduced to retain the current behavior for clients who rely on it. This flag will be documented and configurable.