diff options
Diffstat (limited to 'doc/user/project/integrations/webhooks.md')
| -rw-r--r-- | doc/user/project/integrations/webhooks.md | 57 |
1 files changed, 53 insertions, 4 deletions
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index ace5783c852..e823391401d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -62,7 +62,8 @@ You can configure a webhook for a group or a project. ## Test a webhook -You can trigger a webhook manually, to ensure it's working properly. +You can trigger a webhook manually, to ensure it's working properly. You can also send +a test request to re-enable a [disabled webhook](#re-enable-disabled-webhooks). For example, to test `push events`, your project should have at least one commit. The webhook uses this commit in the webhook. @@ -72,6 +73,8 @@ To test a webhook: 1. Scroll down to the list of configured webhooks. 1. From the **Test** dropdown list, select the type of event to test. +You can also test a webhook from its edit page. +  ## Create an example webhook receiver @@ -143,7 +146,32 @@ GitLab webhooks, keep in mind the following: GitLab assumes the hook failed and retries it. Most HTTP libraries take care of the response for you automatically but if you are writing a low-level hook, this is important to remember. -- GitLab ignores the HTTP status code returned by your endpoint. +- GitLab usually ignores the HTTP status code returned by your endpoint, + unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). + +### Failing webhooks + +> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. +The feature is not ready for production use. + +If a webhook fails repeatedly, it may be disabled automatically. + +Webhooks that return response codes in the `5xx` range are understood to be failing +intermittently, and are temporarily disabled. This lasts initially +for 10 minutes. If the hook continues to fail, the back-off period is +extended on each retry, up to a maximum disabled period of 24 hours. + +Webhooks that return failure codes in the `4xx` range are understood to be +misconfigured, and these are disabled until you manually re-enable +them. These webhooks are not automatically retried. + +See [troubleshooting](#troubleshoot-webhooks) for information on +how to see if a webhook is disabled, and how to re-enable it. ## How image URLs are displayed in the webhook body @@ -186,6 +214,13 @@ To view the table: 1. In your project, on the left sidebar, select **Settings > Webhooks**. 1. Scroll down to the webhooks. +1. Each [failing webhook](#failing-webhooks) has a badge listing it as: + + - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. + - **Fails to connect** if it is temporarily disabled and will retry later. + +  + 1. Select **Edit** for the webhook you want to view. The table includes the following details about each request: @@ -216,8 +251,8 @@ If the endpoint doesn't send an HTTP response in those 10 seconds, GitLab may assume the webhook failed and retry it. If your webhooks are failing or you are receiving multiple requests, -you can try changing the default timeout value. -In your `/etc/gitlab/gitlab.rb` file, uncomment or add the following setting: +an administrator can try changing the default timeout value +by uncommenting or adding the following setting in `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['webhook_timeout'] = 10 @@ -233,3 +268,17 @@ determined by [CAcert.org](http://www.cacert.org/). If that is not the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. Missing intermediate certificates are common causes of verification failure. + +### Re-enable disabled webhooks + +If a webhook is failing, a banner displays at the top of the edit page explaining +why it is disabled, and when it will be automatically re-enabled. For example: + + + +In the case of a failed webhook, an error banner is displayed: + + + +To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test +request succeeds, the webhook is re-enabled. |