Investigate and plan webhook versioning and deprecation strategy

Why?

While documenting the merge request webhook payload structure in #470063, we identified several deprecated fields that have been included in webhook payloads for backward compatibility for a long time some since GitLab 8.5. There is currently no established strategy for versioning webhooks or safely deprecating and removing outdated fields.

This revealed a broader gap: GitLab lacks a consistent, documented strategy for evolving webhooks across all event types.

This issue is to investigate existing approaches and plan a comprehensive webhook evolution and deprecation strategy that applies to all GitLab webhooks.

Background

Deprecated fields identified in merge request webhooks

Top-level fields:

• repository - deprecated since GitLab 8.5, recommend using project
• labels - deprecated, recommend using object_attributes.labels

Project object fields:

• project.http_url - deprecated since GitLab 8.5, use project.git_http_url
• project.homepage - deprecated since GitLab 8.5, use project.web_url
• project.ssh_url - deprecated since GitLab 8.5, use project.git_ssh_url
• project.url - deprecated since GitLab 8.5, use project.git_ssh_url or project.git_http_url

object_attributes fields:

• object_attributes.assignee_id - deprecated, use object_attributes.assignee_ids
• object_attributes.work_in_progress - deprecated, use object_attributes.draft

other considerations:

• project exists for all issuable types, but we also have duplicated target project within object_attributes.
• Some fields like assignees and reviewers are also top level while others like target and source are nested inside of object_attributes.
• It'd be ideal to have a consistent structure and for us to do that we need a way to deprecate them eventually. Related discussions can be found in !220103 (comment 3036016175)

Current gaps

1. No versioning mechanism: Webhooks lack version identifiers, making it unclear which payload format consumers should expect
2. No deprecation timeline: Deprecated fields remain indefinitely with no planned removal path
3. No migration tooling: Users cannot opt-in to test newer webhook formats before changes are enforced
4. Unclear status: Documentation marks fields as deprecated, but they continue to be sent without indication of when/if they'll be removed

Possible options to consider

This investigation should explore options for managing webhook evolution and document the trade-offs of each approach:

Option A: Deprecation-only approach

• Deprecate fields with clear timelines and communication
• Remove deprecated fields after sufficient notice period
• No versioning required - simpler implementation
• Trade-off: Breaking changes affect all consumers simultaneously

Option B: Webhook versioning

• Version identifier options (payload field, HTTP header, configuration setting)
• How users would select/configure webhook versions
• Supporting multiple versions simultaneously
• Trade-off: Larger implementation effort, ongoing maintenance of multiple versions

Option C: Additive-only(more or less our current status)

• Never remove fields, only add new ones
• Deprecated fields remain forever for backward compatibility
• Trade-off: Payload bloat, technical debt accumulates indefinitely, maintenance burden

Research Questions

1. Industry practices: How do other platforms handle webhook versioning? (GitHub, Stripe, Shopify, etc.)
   • What versioning schemes do they use?
   • How do they communicate deprecations?
   • What are their support timelines?
2. Alignment: How should this align with GitLab's broader API strategy?
   • REST API versioning approach
   • GraphQL evolution patterns
   • Overall deprecation policies
3. Scope: Which webhooks should be included?
   • Start with merge request webhooks as a pilot?
   • Apply to all webhook types?
   • Phased rollout approach?

Deliverables

This investigation should produce:

1. Research summary: Analysis of how other platforms handle webhook versioning
2. Proposed versioning scheme: Concrete proposal for GitLab's webhook versioning approach
3. Deprecation policy: Clear policy document for webhook field deprecation
4. Implementation plan: High-level technical approach and effort estimate if we were to make changes