Add latest changes from gitlab-org/gitlab@master

3 files changed, 41 insertions, 57 deletions

diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md
index 5e584a9f2e9..104d3350656 100644
--- a/doc/user/analytics/index.md
+++ b/doc/user/analytics/index.md
@@ -77,8 +77,13 @@ To retrieve metrics for deployment frequency, use the [GraphQL](../../api/graphq
 
 ### Lead time for changes
 
-Lead time for changes measures the time to deliver a feature once it has been developed,
-as described in [Measuring DevOps Performance](https://devops.com/measuring-devops-performance/).
+DORA Lead time for changes measures the time to successfully deliver a feature into production.
+This metric reflects the efficiency of CI/CD pipelines.
+
+In GitLab, Lead time for changes calculates the median time it takes for a merge request to get merged into production.
+We measure "FROM code committed TO code successfully running in production" without adding the "coding_time" to the calculation.
+
+Over time, the lead time for changes should decrease, while your team's performance should increase.
 
 Lead time for changes displays in several charts:
 
@@ -88,6 +93,9 @@ Lead time for changes displays in several charts:
 
 To retrieve metrics for lead time for changes, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs.
 
+- The definition of lead time for change can vary widely, which often creates confusion within the industry. 
+- "Lead time for changes" is not the same as "Lead time". In the value stream, "Lead time" measures the time it takes for work on issue to move from the moment it's requested (Issue created) to the time it's fulfilled and delivered (Issue closed).
+
 ### Time to restore service
 
 Time to restore service measures how long it takes an organization to recover from a failure in production.
diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md
index ed9bf8e3f45..d3d50ee1a8f 100644
--- a/doc/user/gitlab_com/index.md
+++ b/doc/user/gitlab_com/index.md
@@ -249,10 +249,13 @@ The limit varies depending on your plan and the number of seats in your subscrip
 |----------------------|-------------------------|
 | Number of webhooks   | `100` per project, `50` per group |
 | Maximum payload size | 25 MB                   |
+| Timeout              | 10 seconds              |
 
-For self-managed instance limits, see
-[Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit)
-and [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks).
+For self-managed instance limits, see:
+
+- [Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit).
+- [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks).
+- [Webhook timeout](../../administration/instance_limits.md#webhook-timeout).
 
 ## Runner SaaS
 
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index a2dc892d1e2..e703585b6d2 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -64,45 +64,25 @@ You can configure a webhook for a group or a project.
 
 ## Configure your webhook receiver endpoint
 
-Webhook receivers should be *fast* and *stable*.
-Slow and unstable receivers may be disabled temporarily to ensure system reliability.
-If you are writing your own endpoint (web server) to receive GitLab webhooks, keep in mind the following:
-
-- Your endpoint should send its HTTP response as fast as possible.
-  You should aim for sub-second response times in all circumstances.
-  If the response takes longer than the configured timeout, GitLab assumes the
-  hook failed, which can lead to retries and potentially cause duplicate
-  events.
-  To customize the timeout, see
-  [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered).
-- Your endpoint should ALWAYS return a valid HTTP response. If not,
-  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 usually ignores the HTTP status code returned by your endpoint,
-  unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks).
-
-Best practices for a webhook receiver:
-
-- Prefer to return `200` or `201` status responses.
-  Only return error statuses (in the `4xx` range) to
-  indicate that the webhook has been misconfigured. For example, if your receiver
-  only supports push events, it is acceptable to return `400` if sent an issue
-  payload, since that is an indication that the hook has been set up
-  incorrectly. Alternatively, it is acceptable to ignore unrecognized event
-  payloads. Never return `500` status responses if the event has been handled.
-- Your service should be idempotent. In some circumstances (including
-  timeouts), the same event may be sent twice. Be prepared to handle duplicate
-  events. You can reduce the chances of this by ensuring that your endpoint is
+Webhook receiver endpoints should be fast and stable.
+Slow and unstable receivers can be [disabled automatically](#failing-webhooks) to ensure system reliability. Webhooks that fail can lead to retries, [which cause duplicate events](#webhook-fails-or-multiple-webhook-requests-are-triggered).
+
+Endpoints should follow these best practices:
+
+- **Respond quickly with a `200` or `201` status response.** Avoid any significant processing of webhooks in the same request.
+  Instead, implement a queue to handle webhooks after they are received. The timeout limit for webhooks is [10 seconds on GitLab.com](../../../user/gitlab_com/index.md#other-limits).
+- **Be prepared to handle duplicate events.** In [some circumstances](#webhook-fails-or-multiple-webhook-requests-are-triggered), the same event may be sent twice. To mitigate this issue, ensure your endpoint is
   reliably fast and stable.
-- Keep response payloads as short as possible. Empty responses are
-  fine. GitLab does not examine the response body, and it is only
-  stored so you can examine it later in the logs.
-- Limit the number and size of response headers. Only send headers that would
-  help you diagnose problems when examining the web hook logs.
-- To support fast response times, perform I/O or computationally intensive
-  operations asynchronously. You may indicate that the webhook is
-  asynchronous by returning `201`.
+- **Keep the response headers and body minimal.**
+  GitLab does not examine the response headers or body. GitLab stores them so you can examine them later in the logs to help diagnose problems. You should limit the number and size of headers returned. You can also respond to the webhook request with an empty body.
+- Only return client error status responses (in the `4xx` range) to
+  indicate that the webhook has been misconfigured. Responses in this range can lead to your webhooks being [automatically disabled](#failing-webhooks). For example, if your receiver
+  only supports push events, you can return `400` if sent an issue
+  payload, as that is an indication that the hook has been set up
+  incorrectly. Alternatively, you can ignore unrecognized event
+  payloads.
+- Never return `500` server error status responses if the event has been handled as this can cause the webhook to be [temporarily disabled](#failing-webhooks).
+- Invalid HTTP responses are treated as failed requests.
 
 ### Failing webhooks
 
@@ -283,20 +263,6 @@ To repeat the delivery with the same data, select **Resend Request**.
 NOTE:
 If you update the URL or secret token of the webhook, data is delivered to the new address.
 
-### Webhook fails or multiple webhook requests are triggered
-
-When GitLab sends a webhook, it expects a response in 10 seconds by default.
-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,
-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
-```
-
 ### Unable to get local issuer certificate
 
 When SSL verification is enabled, you might get an error that GitLab cannot
@@ -308,6 +274,13 @@ 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.
 
+### Webhook fails or multiple webhook requests are triggered
+
+If you are receiving multiple webhook requests, the webhook might have timed out and
+been retried.
+
+GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout).
+
 ### Re-enable disabled webhooks
 
 > - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default.