Merge pull request #8091 from JKirsch1/refresh-service-hook-troubleshooting-article

Freshness Edit: Azure DevOps - Service hooks

Author: denrea

docs/service-hooks/media/troubleshoot/azure-devops-service-hooks.png

@@ -1,142 +1,148 @@
 ---
 ms.subservice: azure-devops-service-hooks
-ms.topic: conceptual
-title: Troubleshoot your service hooks integrations | Azure DevOps Services
-description: Troubleshoot problems with the services you've integrated with your organization.
+ms.topic: troubleshooting-general
+title: Troubleshoot Service Hook Integrations
+description: Find out how to access the history of service hook subscriptions in Azure DevOps. Get information about HTTP response failures that affect subscription states.
 ms.assetid: dcf00653-24c5-4ab6-b9e8-19ec098bbb66
 ms.custom: engagement-fy23
 ms.author: chcomley
 author: chcomley
 monikerRange: '<= azure-devops'
-ms.date: 12/02/2022
+ms.date: 07/03/2025
+# customer intent: As a team member, I want to become familiar with service hook failure types and find out how to access the history of subscriptions so that I can troubleshoot problems with service hooks in Azure DevOps.
 ---
 
 # Troubleshoot service hooks
 
-[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)]
+[!INCLUDE [Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020](../includes/version-gt-eq-2020.md)]
 
-Use this article for general troubleshooting guidance and answers to frequently asked questions (FAQs).
+This article offers general troubleshooting guidance for Azure DevOps service hooks. It also provides answers to frequently asked questions (FAQs).
 
 ## View activity and debug problems
 
-The **Service Hooks** page in the web access admin shows your recent activity (last 14 days)
-for each subscription, and whether a subscription is enabled, disabled, or restricted.
+The **Service Hooks** page in the web access admin summarizes activity from the last seven days for each subscription. The page also shows whether each subscription is enabled, disabled, or restricted.
 
-You can access detailed history about a subscription including detailed request/response data, which is useful for debugging a problematic service or subscription.
-
-::: moniker range="<=azure-devops"
+For each subscription, you can access a detailed history that includes the complete request and response data for each event. This information can help you debug a problematic service or subscription.
 
 1. To view the activity and status of your subscriptions, go to the **Service Hooks** page. 
 
-   :::image type="content" source="media/troubleshoot/devops-service-hooks.PNG" alt-text="Screenshot showing view of activity and status of subscriptions.":::
+   :::image type="content" source="media/troubleshoot/azure-devops-service-hooks.png" alt-text="Screenshot of the Service Hooks page showing the state, status, and other data for subscriptions. Project settings and Service hooks are highlighted." lightbox="media/troubleshoot/azure-devops-service-hooks.png":::
 
 1. To view detailed activity for a subscription, including full request, response, and event payload data, select a subscription in the table, and then select **History**.
 
-   :::image type="content" source="media/troubleshoot/detailed-activity.png" alt-text="Screenshot showing detailed view of activity for a subscription.":::
-
-::: moniker-end
+   :::image type="content" source="media/troubleshoot/detailed-activity.png" alt-text="Screenshot that shows the history of a subscription, with detailed information for a failed event, such as the status, message, and error message." lightbox="media/troubleshoot/detailed-activity.png":::
 
 ## Subscription failures and probation (restricted)
 
+If the HTTP response to a notification request indicates an error, the severity of the failure determines how Azure DevOps responds. Certain types of failures can disable subscriptions or put them on probation.
+
 ### Failure types
-Failures from a Service Hooks notification are grouped into the following categories:
 
-* Terminal Failures
-* Transient Failures
-* Enduring Failures
+Failures from service hook notifications are grouped into the following categories:
+
+* Terminal failures
+* Transient failures
+* Enduring failures
 
-#### Terminal Failures
+The error code from the HTTP response determines how Azure DevOps categorizes the failure.
 
-The only Terminal Failure is HTTP Status Code 410 (Gone). When a subscription sees a Terminal Failure, it's automatically disabled no matter its prior status.
+#### Terminal failures
 
-#### Transient Failures
+The only HTTP status code that's categorized as a terminal failure is 410 (Gone).
+
+When a terminal failure occurs in a subscription, the subscription is automatically disabled no matter its prior state.
+
+#### Transient failures
+
+HTTP responses with the following status codes are categorized as transient failures:
 
-When a subscription sees a Transient Failure, it attempts to resend the notification up to eight times, with an increasing delay between each attempt. Transient Failures include the following codes:
 * 408 (Request Timeout)
 * 502 (Bad Gateway)
 * 503 (Service Unavailable)
 * 504 (Gateway Timeout)
 
-#### Sequence of retries for transient failures
+When a transient failure occurs in a subscription, Azure DevOps attempts to resend the notification up to eight times, with an increasing delay between each attempt. 
 
-|Retry #  |Wait time  |
-|---------|---------|
-|Before retry 1    |  wait ~1 second      |
-|Before retry 2     | wait ~2 seconds (total delay of 3 seconds)        |
-|Before retry 3     | wait ~4 seconds (total delay of 7 seconds)        |
-|Before retry 4    | wait ~8 seconds (total delay of 15 seconds)        |
-|Before retry 5     | wait ~16 seconds (total delay of 31 seconds)        |
-|Before retry 6     | wait ~32 seconds (total delay of 63 seconds)      |
-|Before retry 7    | wait ~60 seconds (max backoff time, total delay of 123 seconds)  |
-|Before retry 8    | wait ~60 seconds (max backoff time, total delay of 183 seconds)|
+The following table lists information about retries that are attempted after a transient failure occurs. Included is the approximate _backoff_ time, or the time to wait before attempting to resend a notification. The maximum backoff time is 60 seconds. The table also shows the total delay for each retry.
 
-If the notification exhausts all of its retries and continues to see a Transient Failure for each attempt, the subscription stops trying to send the notification, and treats the notification as if it saw an Enduring Failure.
+| Retry number | Backoff time in seconds | Total delay in seconds |
+|---------|---------|---------|
+| 1 | 1 | 1 |
+| 2 | 2 | 3 |
+| 3 | 4 | 7 |
+| 4 | 8 | 15 |
+| 5 | 16 | 31 |
+| 6 | 32 | 63 |
+| 7 | 60 | 123 |
+| 8 | 60 | 183 |
 
-#### Enduring Failures
+If all retries for a notification are exhausted and each attempt results in a transient failure, the notification is no longer sent. Instead, it's categorized as an enduring failure.
 
-Enduring Failures include all other HTTP failure codes, for example: 404 (Not Found), 500 (Internal Server Error), and so on.
+#### Enduring failures
 
-When a subscription sees an Enduring Failure, it's placed on [probation](#probation).
+All other HTTP failure codes, for example, 404 (Not Found) and 500 (Internal Server Error), result in enduring failures.
 
-### Probation
+When an enduring failure occurs in a subscription, the subscription is placed on [probation](#probation).
 
-While on probation, a subscription is limited in the number of notifications it can send. If the subscription continues to hit Enduring Failures, then it gets increasingly limited, and eventually disabled. If the subscription receives a successful response while on probation, it gets restored to a fully enabled state.
+### Probation
 
-#### Sequence of seven maximum retries while subscription is on probation
+When a subscription is on probation, any new events are lost. The system makes a limited number of attempts to resend the failed notification.
 
-When a subscription is in probation, any new events are lost. Once a retry is successful, the subscription is enabled, and events are published again.
+The following table lists approximate backoff times and total probation times for retries that are attempted during probation. At most seven retries are attempted, and the maximum backoff time for a probation retry is 15 hours.
 
-|Retry #  |Wait time  |
-|---------|---------|
-|Before retry 1    |  wait ~20 minutes      |
-|Before retry 2     | wait ~40 minutes (total probation time of 1 hour)        |
-|Before retry 3     | wait ~1 hour 20 minutes (total probation time of 2.33 hours)        |
-|Before retry 4    | wait ~2 hours 40 minutes (total probation time of 5 hours)        |
-|Before retry 5     | wait ~5 hours 20 minutes (total probation time of 10.33 hours)        |
-|Before retry 6     | wait ~10 hours 40 minutes (total probation time of 21 hours)        |
-|Before retry 7    | wait ~15 hours (max backoff time, total probation time of 36 hours)        |
+| Retry number | Backoff time | Total probation time in hours |
+|---------|---------|---------|
+| 1 | 20 minutes | 0.33 |
+| 2 | 40 minutes | 1 |
+| 3 | 1 hour 20 minutes | 2.33 |
+| 4 | 2 hours 40 minutes | 5 |
+| 5 | 5 hours 20 minutes | 10.33 |
+| 6 | 10 hours 40 minutes | 21 |
+| 7 | 15 hours | 36 |
 
-After seven retries, the subscription status gets set to _DisabledBySystem_ if notifying the consumer fails.
+If the subscription receives a successful response while on probation, it gets restored to a fully enabled state, and events are published again. If all seven retries fail, the subscription state gets set to _DisabledBySystem_.
 
 ## FAQs
 
-<!-- BEGINSECTION class="m-qanda" -->
+### Q: What is the payload limit of a service hook? 
+
+**A:** The payload limit is 2 MB. Larger payloads cause degradation in performance and reliability. As a best practice, service hooks should limit the payload to 2 MB. 
+
+### Q: What does the state Enabled (restricted) mean? 
+
+**A:** A subscription becomes restricted if too many failures occur. Being in the _Enabled (restricted)_ state is the same as being on probation.
 
-### Q: What is the payload limit of a service-hook? 
+### Q: What does the state Disabled (due to failures) mean?
 
-**A:** The payload limit is 2 MB. Larger payloads cause degradation in performance and reliability. As a best practice, service-hooks should limit the payload to 2 MB or less. 
+**A:** A subscription is automatically disabled in the following cases:
 
-### Q: What does the status Enabled (restricted) mean? 
+* A terminal failure is encountered.
+* A series of consecutive failures occurs over a prolonged period.
 
-**A:** A subscription becomes restricted if too many failures occur. Enabled (restricted) is the same as being on probation.
+Notifications that result in transient failures are retried several times before being declared enduring failures. Enduring failure notifications are retried a limited number of times during [probation](#probation). If all probation retries fail, the subscription gets disabled.
 
-### Q: What does the status Disabled (due to failures) mean?
+The following status codes provide examples of each type of failure:
 
-A: A subscription is automatically disabled after a series of consecutive failures over a prolonged period or a _terminal failure_ is encountered.  _Transient failures_ types are retried several times before being declared a failure.  _Enduring failure_ types aren't retried.  The following are examples of each type of failure.
 * Transient: 408 (Request Timeout), 502 (Bad Gateway), 503 (Service Unavailable), 504 (Gateway Timeout)
 * Terminal: 410 (Gone)
 * Enduring: All failures that aren't transient or terminal
 
-### Q: What does the status Disabled (user left project) mean?
+### Q: What does the state Disabled (user left project) mean?
 
 **A:** The user who created the subscription is no longer a member of the team.
 
 ### Q: What should I try if a service hook isn't working? 
 
 **A:** Check the following items:
 
-- Confirm the subscription is enabled
-
-- Confirm the subscription settings are correct (both event filters and actions)
-
-- Look at the history, especially if there are failures
+* Confirm the subscription is enabled.
+* Confirm the subscription settings are correct. Check event filters and actions.
+* Look at the history, especially if there are failures.
 
 ### Q: Can I grant a regular project user the ability to view and manage service hook subscriptions for a project? 
 
-**A:** By default, only project administrators have these permissions. To grant them to other users directly, you can use the [command line tool](../organizations/security/manage-tokens-namespaces.md) or the [Security](/rest/api/azure/devops/security/) REST API. 
+**A:** By default, only project administrators have these permissions. To grant them to other users directly, you can use the [command-line tool](../organizations/security/manage-tokens-namespaces.md) or the [Security](/rest/api/azure/devops/security/) REST API. 
 
 ### Q: Can I programmatically create subscriptions? 
 
-**A:** Yes, use [REST APIs](./create-subscription.md).
-
-<!-- ENDSECTION -->
+**A:** Yes, use [REST APIs](create-subscription.md).