Merge b9494a4 into e9fffee

docs/essentials/flaky-tests.md

@@ -7,8 +7,6 @@ Flaky test detection helps identify and manage unreliable tests in a test suite.
 By detecting flaky tests, development teams can take specific actions to address
 these issues and improve the overall reliability of their testing pipeline.
 
-!!! warning "Note: This feature is in closed beta."
-
 !!! info "Definition"
       A test is considered flaky when it produces different results within the same Git commit. For example, the test may fail at one point and subsequently pass without any alterations to the codebase. 
 
@@ -175,10 +173,102 @@ The detailed view also provides a list of flaky occurrences, allowing you to nav
 
 ![detailed_view](img/flaky-tests/dv.png)
 
-### Known issues
 
-* While creating a new filter, you need to search before saving the filter otherwise the contents of the filter do not get saved correctly.
-* Deleting a filter does not automatically switch to the next on the list.
+### Notifications
+
+Flaky tests utilize webhook-based notifications that are dispatched when new flaky tests are identified. When the conditions for notifications are satisfied, Semaphore will transmit an HTTP POST payload to the configured URL of the webhook. This can be utilized, for instance, to establish alerts when new flaky tests emerge for a specific team.
+
+#### Configuring webhook notifications for a project
+
+To enable notifications, follow these steps on the Flaky Tests page:
+
+1. Navigate to the Flaky Tests page.
+2. Click on the bell icon next to the filter actions.
+3. Enter the webhook URL (it must be an HTTPS URL).
+4. Optionally, you can also specify the branches for which you want to receive notifications (leave this field blank if you want to receive notifications for all branches).
+5. Click on Activate and Save.
+
+!!! info "Branches"
+        We allow basic regular expressions in the branches field. For instance, you can use patterns like `release-*` or `.*`.
+        Please note that there's a character limit of 100 for the branches field. If you wish to specify multiple branches, you can separate them using a comma.
+
+![notifications](img/flaky-tests/notifications.png)
+
+#### Notification payload
+
+Your endpoint is set to receive an HTTP POST request with a specific schema.
+This request will have the Content-Type header set to application/json.
+It is expected that your endpoint responds with a status code within the 200 range.
+If the response status code is outside this range, we will attempt to resend the request four additional times,
+employing an exponential backoff strategy for these retries.
+
+```spec
+type: object
+properties:
+  id:
+    type: string
+    format: uuid
+    example: "a01e9b47-7e3c-4165-9007-8a3c1652b31a"
+  project_id:
+    type: string
+    format: uuid
+    example: "4627d711-4aa2-xe1e-bc5c-e0f4491b8735"
+  test_id:
+    type: string
+    format: uuid
+    example: "3177e680-46ac-4c39-b9fa-02c4ba71b644"
+  branch_name:
+    type: string
+    example: "main"
+  test_name:
+    type: string
+    example: "Test 1"
+  test_group:
+    type: string
+    example: "Elixir.Calculator.Test"
+  test_file:
+    type: string
+    example: "calculator_test.exs"
+  test_suite:
+    type: string
+    example: "suite1"
+  created_at:
+    type: string
+    format: date-time
+    example: "2025-03-22T18:24:34.479219+01:00"
+  updated_at:
+    type: string
+    format: date-time
+    example: "2025-03-22T18:24:34.479219+01:00"
+required:
+  - id
+  - project_id
+  - test_id
+  - branch_name
+  - test_name
+  - test_group
+  - test_file
+  - test_suite
+  - created_at
+  - updated_at
+```
+
+Example
+
+```json
+{
+  "id": "a01e9b47-7e3c-4165-9007-8a3c1652b31a",
+  "project_id": "4627d711-4aa2-xe1e-bc5c-e0f4491b8735",
+  "test_id": "3177e680-46ac-4c39-b9fa-02c4ba71b644",
+  "branch_name": "main",
+  "test_name": "Test 1",
+  "test_group": "Elixir.Calculator.Test",
+  "test_file": "calculator_test.exs",
+  "test_suite": "suite1",
+  "created_at": "2025-03-22T18:24:34.479219+01:00",
+  "updated_at": "2025-03-22T18:24:34.479219+01:00"
+}
+```
 
 ## See also