Docs tutorial: Configure webhooks
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Goal and proposal
The main goal is to consolidate the content we already have on webhook configuration in a single tutorial and expand on it in an attempt to address the following overarching goals:
- Help developers get started on building integrations for GitLab
- Add guidance on when to use APIs vs webhooks
We don't have to address these goals in detail, but it would be a good idea to crosslink APIs and webhooks to contrast their functions when appropriate.
Basic outline
We could refactor some or all of these sections for the tutorial:
- Configure a webhook in GitLab
- Configure your webhook receiver endpoint
- Test a webhook
- Create an example webhook receiver
We could also integrate when/how to use webhooks in the tutorial and include a running example so that the workflow describes both configuration and usage.
Having Webhooks under https://docs.gitlab.com/ee/user/project/integrations has been a source of confusion lately. Some users assume that the content on that page only applies to project webhooks even when project or group is added explicitly. If there's a lot of shared information between project and group webhooks and having a dedicated Group webhooks page is not practical, we could move webhooks out from under project integrations. For example, the updated path could be https://docs.gitlab.com/ee/integration/webhooks.html instead of https://docs.gitlab.com/ee/user/project/integrations/webhooks.html.
Where to place
The tutorial could be a child page of Webhooks. I could imagine the left navigation would look like this:
- Webooks
- Tutorial: Configure webhooks
- Webhook events
- Rake tasks