Document SendSecurityMonitoringNotificationPreview endpoint

.generator/schemas/v2/openapi.yaml

@@ -23283,6 +23283,8 @@ components:
           $ref: "#/components/schemas/Enabled"
         name:
           $ref: "#/components/schemas/RuleName"
+        routing:
+          $ref: "#/components/schemas/NotificationRuleRouting"
         selectors:
           $ref: "#/components/schemas/Selectors"
         targets:
@@ -57809,6 +57811,72 @@ components:
         - targets
         - version
       type: object
+    NotificationRulePreviewNotificationStatus:
+      description: The notification status for the given rule type. `SUCCESS` means a matching event was found and the notification was sent successfully. `DEFAULT` means no matching event was found and a default placeholder notification was sent instead. `ERROR` means an error occurred while sending the notification.
+      enum:
+        - SUCCESS
+        - DEFAULT
+        - ERROR
+      example: SUCCESS
+      type: string
+      x-enum-varnames:
+        - SUCCESS
+        - DEFAULT
+        - ERROR
+    NotificationRulePreviewResponse:
+      description: Response from the notification preview request.
+      properties:
+        data:
+          $ref: "#/components/schemas/NotificationRulePreviewResponseData"
+      required:
+        - data
+      type: object
+    NotificationRulePreviewResponseAttributes:
+      description: Attributes of the notification preview response.
+      properties:
+        preview_results:
+          $ref: "#/components/schemas/NotificationRulePreviewResults"
+      required:
+        - preview_results
+      type: object
+    NotificationRulePreviewResponseData:
+      description: The notification preview response data.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/NotificationRulePreviewResponseAttributes"
+        type:
+          $ref: "#/components/schemas/NotificationRulePreviewResponseType"
+      required:
+        - type
+        - attributes
+      type: object
+    NotificationRulePreviewResponseType:
+      description: The type of the notification preview response.
+      enum:
+        - notification_preview_response
+      example: notification_preview_response
+      type: string
+      x-enum-varnames:
+        - NOTIFICATION_PREVIEW_RESPONSE
+    NotificationRulePreviewResult:
+      description: The preview result for a single rule type.
+      properties:
+        notification_status:
+          $ref: "#/components/schemas/NotificationRulePreviewNotificationStatus"
+        rule_type:
+          $ref: "#/components/schemas/RuleTypesItems"
+      required:
+        - rule_type
+        - notification_status
+      type: object
+    NotificationRulePreviewResults:
+      description: List of preview results for each rule type matched by the notification rule.
+      example:
+        - notification_status: DEFAULT
+          rule_type: log_detection
+      items:
+        $ref: "#/components/schemas/NotificationRulePreviewResult"
+      type: array
     NotificationRuleQuery:
       description: The query is composed of one or several key:value pairs, which can be used to filter security issues on tags and attributes.
       example: (source:production_service OR env:prod)
@@ -57819,6 +57887,22 @@ components:
         data:
           $ref: "#/components/schemas/NotificationRule"
       type: object
+    NotificationRuleRouting:
+      description: Routing configuration for the notification rule.
+      properties:
+        mode:
+          $ref: "#/components/schemas/NotificationRuleRoutingMode"
+      required:
+        - mode
+      type: object
+    NotificationRuleRoutingMode:
+      description: The routing mode for the notification rule. `manual` sends notifications to the configured targets.
+      enum:
+        - manual
+      example: manual
+      type: string
+      x-enum-varnames:
+        - MANUAL
     NotificationRulesType:
       description: The rule type associated to notification rules.
       enum:
@@ -67052,6 +67136,8 @@ components:
           $ref: "#/components/schemas/Enabled"
         name:
           $ref: "#/components/schemas/RuleName"
+        routing:
+          $ref: "#/components/schemas/NotificationRuleRouting"
         selectors:
           $ref: "#/components/schemas/Selectors"
         targets:
@@ -73361,6 +73447,7 @@ components:
         - iac_misconfiguration
         - sast_vulnerability
         - secret_vulnerability
+      example: log_detection
       type: string
       x-enum-varnames:
         - APPLICATION_SECURITY
@@ -159547,6 +159634,72 @@ paths:
       x-unstable: |-
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
+  /api/v2/security_monitoring/configuration/notification_rules/send_notification_preview:
+    post:
+      description: Send a notification preview to test that a notification rule's targets are properly configured.
+      operationId: SendSecurityMonitoringNotificationPreview
+      requestBody:
+        content:
+          application/json:
+            examples:
+              default:
+                value:
+                  data:
+                    attributes:
+                      enabled: true
+                      name: Rule 1
+                      selectors:
+                        query: env:prod
+                        rule_types:
+                          - log_detection
+                        severities:
+                          - critical
+                        trigger_source: security_signals
+                      targets:
+                        - "@john.doe@email.com"
+                    type: notification_rules
+            schema:
+              $ref: "#/components/schemas/CreateNotificationRuleParameters"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                default:
+                  value:
+                    data:
+                      attributes:
+                        preview_results:
+                          - notification_status: DEFAULT
+                            rule_type: log_detection
+                      type: notification_preview_response
+              schema:
+                $ref: "#/components/schemas/NotificationRulePreviewResponse"
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
+        "403":
+          $ref: "#/components/responses/NotAuthorizedResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_notification_profiles_read
+      summary: Test a notification rule
+      tags:
+        - Security Monitoring
+      x-codegen-request-body-name: body
+      "x-permission":
+        operator: OR
+        permissions:
+          - security_monitoring_notification_profiles_read
   /api/v2/security_monitoring/configuration/security_filters:
     get:
       description: Get the list of configured security filters with their definitions.

examples/v2/security-monitoring/SendSecurityMonitoringNotificationPreview.java

@@ -0,0 +1,62 @@
+// Test a notification rule returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.SecurityMonitoringApi;
+import com.datadog.api.client.v2.model.CreateNotificationRuleParameters;
+import com.datadog.api.client.v2.model.CreateNotificationRuleParametersData;
+import com.datadog.api.client.v2.model.CreateNotificationRuleParametersDataAttributes;
+import com.datadog.api.client.v2.model.NotificationRulePreviewResponse;
+import com.datadog.api.client.v2.model.NotificationRuleRouting;
+import com.datadog.api.client.v2.model.NotificationRuleRoutingMode;
+import com.datadog.api.client.v2.model.NotificationRulesType;
+import com.datadog.api.client.v2.model.RuleSeverity;
+import com.datadog.api.client.v2.model.RuleTypesItems;
+import com.datadog.api.client.v2.model.Selectors;
+import com.datadog.api.client.v2.model.TriggerSource;
+import java.util.Arrays;
+import java.util.Collections;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);
+
+    CreateNotificationRuleParameters body =
+        new CreateNotificationRuleParameters()
+            .data(
+                new CreateNotificationRuleParametersData()
+                    .attributes(
+                        new CreateNotificationRuleParametersDataAttributes()
+                            .enabled(true)
+                            .name("Rule 1")
+                            .routing(
+                                new NotificationRuleRouting()
+                                    .mode(NotificationRuleRoutingMode.MANUAL))
+                            .selectors(
+                                new Selectors()
+                                    .query("(source:production_service OR env:prod)")
+                                    .ruleTypes(
+                                        Arrays.asList(
+                                            RuleTypesItems.MISCONFIGURATION,
+                                            RuleTypesItems.ATTACK_PATH))
+                                    .severities(Collections.singletonList(RuleSeverity.CRITICAL))
+                                    .triggerSource(TriggerSource.SECURITY_FINDINGS))
+                            .targets(Collections.singletonList("@john.doe@email.com"))
+                            .timeAggregation(86400L))
+                    .type(NotificationRulesType.NOTIFICATION_RULES));
+
+    try {
+      NotificationRulePreviewResponse result =
+          apiInstance.sendSecurityMonitoringNotificationPreview(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println(
+          "Exception when calling SecurityMonitoringApi#sendSecurityMonitoringNotificationPreview");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}