Document the system hook response fields the API sends

What does this MR do and why?

API::Entities::Hook exposes twenty fields, and the three example responses on this page show thirteen of them. This adds the seven that were missing to all three: organization_id, alert_status, disabled_until, push_events_branch_filter, branch_filter_strategy, custom_webhook_template and custom_headers.

Two of those seven, push_events_branch_filter and branch_filter_strategy, were already documented on this page as request parameters, so the page said you could set them and never showed them coming back.

I put each field where lib/api/entities/hook.rb exposes it rather than at the end of the object, so the examples now read in entity order. The values follow the ones already used for the same fields on doc/api/project_webhooks.md, including the key-only shape of custom_headers: the entity renders it through masked_custom_headers, which is custom_headers.keys.map { |k| { key: k } }, so the value is not sent at all.

organization_id is exposed under if: ->(hook, _) { hook.is_a?(SystemHook) }. Every record this API presents is a SystemHook, so it is always present here, and it is correctly absent from the project and group webhook pages, which document the same entity rendered for other hook types.

I also added custom_webhook_template to the two request attribute tables. The hook_parameters block in lib/api/system_hooks.rb declares it as an accepted parameter of both POST /hooks and PUT /hooks/:hook_id, and neither table listed it.

The mock payload under "Test system hook" is not a hook entity, so it is untouched.

I found this while adding the same seven fields to the Go API client, in gitlab-org/api/client-go!3048.

MR acceptance checklist

This change is documentation only. No endpoint, parameter or behaviour changes. I parsed every JSON block on the page after editing: all four still parse, the three hook examples carry the seven new keys, and the mock test payload carries none of them.

Merge request reports

Loading
Loading