Document Duo flow webhook callbacks

Thomas Schmidtrequested to merge
duo/docs/618579-duo-flow-webhook-callbacks into master

What does this MR do and why?

Documents the Duo flow webhook callback feature that shpis as experimental in 19.4 Duo Flow Webhook Callbacks - Experimental Release (gitlab-org#22922 - closed), so an integration can be pushed flow lifecycle events instead of polling the Flows API.

Changes:

  • New page doc/user/duo_agent_platform/flows/webhook_callbacks.md, the integrator guide: eligible webhooks, turning the checkbox on, callback_hook_id, and endpoint handling.
  • New GitLab Duo flow events topic in webhook_events.md with the request header, the three events, payload examples, and an attribute table. Plus a row in the events table at the top.
  • callback_hook_id and client_reference added to the Flows API Trigger a flow attributes, with history, a flag note, and the 400 cases.
  • One optional step in the Create a webhook task for the new checkbox.
  • The checkbox Learn more link now points at the new page instead of the flows overview.

Removal of the organization-scoped registration API

This MR also deletes the Register / List / Get / Delete a flow callback endpoint sections added in !248060 (closed).

That API is being removed in #627862 (closed), and it does not work end to end today: it tells readers to pass the returned id as callback_hook_id, but the trigger path resolves callback_hook_id only through CallbackHooksFinder, which returns project and group webhooks. A hook registered through that API is rejected. The style guide says to delete content for features that are not generally available rather than deprecate it.

doc/auth/tokens/fine_grained_access_tokens_rest.md still lists those four routes. It is generated by lib/tasks/gitlab/permissions/routes/docs_task.rb, so it regenerates when the permission definitions are removed. Left untouched deliberately.

Deliberate scope decisions

  • flow.progress is not documented. It is still in review in Deliver Duo flow progress to callback webhooks (!251157 - merged), whose base predates the delivery MR, so the payload may still change. Those docs should ship in that MR or a follow-up.
  • Tier matches the flows page, Free (via credits), Premium, Ultimate. An earlier revision of this MR said Premium and Ultimate, on the assumption that Gate the Duo flow callback capability on Duo Ag... (#627863 - closed) would add a tier gate. It does not: it gates on duo_agent_platform_enabled, a settings switch that defaults to on and implies no licence. Entitlement is enforced when a flow is triggered, and flows are available on Free through credits, so callbacks inherit that tier. Group webhooks are the one exception, because they are a licensed feature in their own right, and that is now called out in the prerequisites.
  • Offering omits GitLab Dedicated, because doc/development/documentation/feature_flags.md says not to list Dedicated for a feature disabled on GitLab Self-Managed, and the flag is disabled by default. Happy to change this if a technical writer reads that rule differently.

References

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

No changelog entry: documentation-only content for a feature behind a default-off feature flag.

Edited by Thomas Schmidt

Merge request reports