### 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 https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220103#note_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