new: Add webhook acknowledge setting and global trace (#2019)

* feat(webhooks): Add acknowledge setting and global trace ID

This commit implements webhook acknowledgment and global trace ID features:
- Add webhookAcknowledge setting in workspace config
- Support MOON_TRACE_ID environment variable
- Update documentation
- Add test cases

Closes #1961

* fix tests, format and lint

* fix last linting issue

Author: harlequin

crates/action-pipeline/src/action_pipeline.rs

@@ -406,14 +406,20 @@ impl ActionPipeline {
         // For security and privacy purposes, only send webhooks from a CI environment
         if is_ci() || is_test_env() {
             if let Some(webhook_url) = &self.app_context.workspace_config.notifier.webhook_url {
+                let require_acknowledge = self
+                    .app_context
+                    .workspace_config
+                    .notifier
+                    .webhook_acknowledge;
+
                 debug!(
                     url = webhook_url,
                     "Subscribing webhook events ({} enabled)",
                     color::property("notifier.webhookUrl"),
                 );
 
                 self.emitter
-                    .subscribe(WebhooksSubscriber::new(webhook_url))
+                    .subscribe(WebhooksSubscriber::new(webhook_url, require_acknowledge))
                     .await;
             }
         }

crates/action-pipeline/src/subscribers/webhooks_subscriber.rs

@@ -8,9 +8,9 @@ pub struct WebhooksSubscriber {
 }
 
 impl WebhooksSubscriber {
-    pub fn new(url: &str) -> Self {
+    pub fn new(url: &str, require_acknowledge: bool) -> Self {
         WebhooksSubscriber {
-            notifier: WebhooksNotifier::new(url.to_owned()),
+            notifier: WebhooksNotifier::new(url.to_owned(), require_acknowledge),
         }
     }
 }

crates/cli/tests/run_webhooks_test.rs

@@ -7,6 +7,7 @@ fn sandbox(uri: String) -> Sandbox {
 
     workspace_config.notifier = Some(PartialNotifierConfig {
         webhook_url: Some(format!("{uri}/webhook")),
+        webhook_acknowledge: Some(false),
     });
 
     let sandbox = create_sandbox_with_config(

crates/config/src/workspace/notifier_config.rs

@@ -8,5 +8,8 @@ config_struct!(
         /// A secure URL in which to send webhooks to.
         #[setting(validate = validate::url_secure)]
         pub webhook_url: Option<String>,
+        /// Whether webhook requests require acknowledgment (2xx response).
+        #[setting(default = false)]
+        pub webhook_acknowledge: bool,
     }
 );

crates/config/tests/workspace_config_test.rs

@@ -918,7 +918,8 @@ extensions:
             assert_eq!(
                 config.notifier,
                 NotifierConfig {
-                    webhook_url: Some("http://localhost".into())
+                    webhook_url: Some("http://localhost".into()),
+                    webhook_acknowledge: false
                 }
             );
             assert_eq!(

crates/notifier/src/webhooks.rs

@@ -4,6 +4,7 @@ use moon_time::chrono::NaiveDateTime;
 use moon_time::now_timestamp;
 use serde::Serialize;
 use starbase_utils::json;
+use std::env;
 use tokio::task::JoinHandle;
 use tracing::{debug, trace, warn};
 use uuid::Uuid;
@@ -21,21 +22,30 @@ pub struct WebhookPayload<'data, T: Serialize> {
     pub type_of: &'data str,
 
     pub uuid: &'data str,
+
+    pub trace: &'data str,
 }
 
 pub async fn notify_webhook(
     url: String,
     body: String,
+    require_acknowledge: bool,
 ) -> Result<reqwest::Response, reqwest::Error> {
-    reqwest::Client::new()
+    let response = reqwest::Client::new()
         .post(url)
         .body(body)
         .header("Accept", "application/json")
         .header("Content-Type", "application/json")
         .header("Connection", "keep-alive")
         .header("Keep-Alive", "timeout=30, max=120")
         .send()
-        .await
+        .await?;
+
+    if require_acknowledge && !response.status().is_success() {
+        return Err(response.error_for_status().unwrap_err());
+    }
+
+    Ok(response)
 }
 
 pub struct WebhooksNotifier {
@@ -44,11 +54,13 @@ pub struct WebhooksNotifier {
     requests: Vec<JoinHandle<()>>,
     url: String,
     uuid: String,
+    trace: String,
     verified: bool,
+    require_acknowledge: bool,
 }
 
 impl WebhooksNotifier {
-    pub fn new(url: String) -> Self {
+    pub fn new(url: String, require_acknowledge: bool) -> Self {
         debug!("Creating webhooks notifier for {}", color::url(&url));
 
         WebhooksNotifier {
@@ -60,8 +72,10 @@ impl WebhooksNotifier {
             } else {
                 Uuid::new_v4().to_string()
             },
+            trace: env::var("MOON_TRACE_ID").unwrap_or_default(),
             url,
             verified: false,
+            require_acknowledge,
         }
     }
 
@@ -78,15 +92,17 @@ impl WebhooksNotifier {
             event,
             type_of: name,
             uuid: &self.uuid,
+            trace: &self.trace,
         };
         let body = json::format(&payload, false)?;
         let url = self.url.to_owned();
+        let require_acknowledge = self.require_acknowledge.to_owned();
 
         // For the first event, we want to ensure that the webhook URL is valid
         // by sending the request and checking for a failure. If failed,
         // we will disable subsequent requests from being called.
         if !self.verified {
-            let response = notify_webhook(url, body).await;
+            let response = notify_webhook(url, body, require_acknowledge).await;
 
             if response.is_err() || !response.unwrap().status().is_success() {
                 self.enabled = false;
@@ -98,9 +114,11 @@ impl WebhooksNotifier {
         }
         // For every other event, we will make the request and ignore the result.
         // We will also avoid awaiting the request to not slow down the overall runner.
-        else {
-            self.requests.push(tokio::spawn(async {
-                let _ = notify_webhook(url, body).await;
+        else if require_acknowledge {
+            let _ = notify_webhook(url.clone(), body, true).await;
+        } else {
+            self.requests.push(tokio::spawn(async move {
+                let _ = notify_webhook(url, body, false).await;
             }));
         }
 

website/docs/config/workspace.mdx

@@ -521,6 +521,26 @@ notifier:
   webhookUrl: 'https://api.company.com/some/endpoint'
 ```
 
+### `acknowledge`
+
+<HeadingApiLink to="/api/types/interface/NotifierConfig#acknowledge" />
+
+When enabled, webhook notfier will wait for request result and validates the return code for 2xx.
+Defaults to `false`.
+
+:::warning
+
+Activating this setting will slow down your pipeline, because every webhook request will be evaluated!
+
+:::
+
+```yaml title=".moon/workspace.yml" {2}
+notifier:
+  webhookUrl: 'https://api.company.com/some/endpoint'
+  webhookAcknowledge: true
+```
+
+
 ## `pipeline`
 
 <HeadingApiLink to="/api/types/interface/WorkspaceConfig#pipeline" />

website/docs/guides/webhooks.mdx

@@ -24,6 +24,7 @@ Every webhook event is posted with the following request body, known as a payloa
 - `createdAt` (`string`) - When the event was created, as a UTC timestamp in ISO 8601 (RFC 3339)
   format.
 - `uuid` (`string`) - A unique identifier for all webhooks in the current run batch.
+- `trace` (`string`) - A unique identifier for all webhooks in the overall run batch. Can be defined via `MOON_TRACE_ID` environment variable.
 
 ```json
 {
@@ -33,7 +34,8 @@ Every webhook event is posted with the following request body, known as a payloa
     // ...
   },
   "createdAt": "...",
-  "uuid": "..."
+  "uuid": "...",
+  "trace": "..."
 }
 ```