Docs tutorial: Configure webhooks
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