feat(server): add signed automation review webhooks

Author: haasonsaas

TODO.md

@@ -121,7 +121,7 @@ This roadmap is derived from deep research into Greptile's public docs, blog, MC
 76. [x] Add APIs for comment resolution and lifecycle updates, not just thumbs.
 77. [x] Add an MCP server for DiffScope with review, analytics, and rule-management tools.
 78. [x] Add reusable agent skills/workflows for checking PR readiness and running fix loops.
-79. [ ] Add signed webhook or event-stream integration for downstream automation consumers.
+79. [x] Add signed webhook or event-stream integration for downstream automation consumers.
 80. [ ] Add rate-limited API auth and audit trails for automation-heavy deployments.
 
 ## 9. Infra, Self-Hosting, and Enterprise Operations

src/config.rs

@@ -116,6 +116,17 @@ pub struct GitHubConfig {
     pub webhook_secret: Option<String>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct AutomationConfig {
+    /// Outbound webhook URL for downstream automation consumers.
+    #[serde(default, rename = "automation_webhook_url")]
+    pub webhook_url: Option<String>,
+
+    /// Optional shared secret for signing outbound automation webhooks.
+    #[serde(default, rename = "automation_webhook_secret")]
+    pub webhook_secret: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AgentConfig {
     /// Enable agent loop for iterative tool-calling review (default false).
@@ -453,6 +464,9 @@ pub struct Config {
     #[serde(default, flatten)]
     pub github: GitHubConfig,
 
+    #[serde(default, flatten)]
+    pub automation: AutomationConfig,
+
     /// When true, run separate specialized LLM passes for security, correctness,
     /// and style instead of a single monolithic review prompt.
     #[serde(default = "default_false")]
@@ -655,6 +669,7 @@ impl Default for Config {
             rule_priority: Vec::new(),
             providers: HashMap::new(),
             github: GitHubConfig::default(),
+            automation: AutomationConfig::default(),
             multi_pass_specialized: false,
             agent: AgentConfig::default(),
             verification: VerificationConfig::default(),
@@ -831,33 +846,20 @@ impl Config {
                 .ok()
                 .filter(|s| !s.trim().is_empty());
         }
-
-        // Validate base_url: must be a valid http/https URL with a host
-        if let Some(ref raw_url) = self.base_url {
-            match url::Url::parse(raw_url) {
-                Ok(parsed) => {
-                    if !matches!(parsed.scheme(), "http" | "https") {
-                        warn!(
-                            "base_url '{}' uses unsupported scheme '{}' (expected http or https), ignoring",
-                            raw_url,
-                            parsed.scheme()
-                        );
-                        self.base_url = None;
-                    } else if parsed.host().is_none() {
-                        warn!("base_url '{}' has no valid host, ignoring", raw_url);
-                        self.base_url = None;
-                    }
-                }
-                Err(err) => {
-                    warn!(
-                        "base_url '{}' is not a valid URL ({}), ignoring",
-                        raw_url, err
-                    );
-                    self.base_url = None;
-                }
-            }
+        if self.automation.webhook_url.is_none() {
+            self.automation.webhook_url = std::env::var("DIFFSCOPE_AUTOMATION_WEBHOOK_URL")
+                .ok()
+                .filter(|s| !s.trim().is_empty());
+        }
+        if self.automation.webhook_secret.is_none() {
+            self.automation.webhook_secret = std::env::var("DIFFSCOPE_AUTOMATION_WEBHOOK_SECRET")
+                .ok()
+                .filter(|s| !s.trim().is_empty());
         }
 
+        validate_optional_http_url(&mut self.base_url, "base_url");
+        validate_optional_http_url(&mut self.automation.webhook_url, "automation_webhook_url");
+
         // Normalize adapter field
         if let Some(ref adapter) = self.adapter {
             let normalized = adapter.trim().to_lowercase();
@@ -1365,6 +1367,36 @@ impl Config {
     }
 }
 
+fn validate_optional_http_url(url: &mut Option<String>, field_name: &str) {
+    let Some(raw_url) = url.clone() else {
+        return;
+    };
+
+    match url::Url::parse(&raw_url) {
+        Ok(parsed) => {
+            if !matches!(parsed.scheme(), "http" | "https") {
+                warn!(
+                    "{} '{}' uses unsupported scheme '{}' (expected http or https), ignoring",
+                    field_name,
+                    raw_url,
+                    parsed.scheme()
+                );
+                *url = None;
+            } else if parsed.host().is_none() {
+                warn!("{} '{}' has no valid host, ignoring", field_name, raw_url);
+                *url = None;
+            }
+        }
+        Err(err) => {
+            warn!(
+                "{} '{}' is not a valid URL ({}), ignoring",
+                field_name, raw_url, err
+            );
+            *url = None;
+        }
+    }
+}
+
 fn default_model() -> String {
     "anthropic/claude-opus-4.5".to_string()
 }
@@ -1746,6 +1778,39 @@ mod tests {
         assert!(config.base_url.is_none());
     }
 
+    #[test]
+    fn normalize_accepts_automation_webhook_url_https() {
+        let mut config = Config {
+            automation: AutomationConfig {
+                webhook_url: Some("https://automation.example.com/hooks/reviews".to_string()),
+                ..AutomationConfig::default()
+            },
+            ..Config::default()
+        };
+
+        config.normalize();
+
+        assert_eq!(
+            config.automation.webhook_url.as_deref(),
+            Some("https://automation.example.com/hooks/reviews")
+        );
+    }
+
+    #[test]
+    fn normalize_rejects_automation_webhook_url_bad_scheme() {
+        let mut config = Config {
+            automation: AutomationConfig {
+                webhook_url: Some("ftp://automation.example.com/hooks/reviews".to_string()),
+                ..AutomationConfig::default()
+            },
+            ..Config::default()
+        };
+
+        config.normalize();
+
+        assert!(config.automation.webhook_url.is_none());
+    }
+
     #[test]
     fn normalize_clamps_max_tokens_above_limit() {
         let mut config = Config {

src/server/api.rs

@@ -226,7 +226,11 @@ mod tests {
             "github_webhook_secret".to_string(),
             serde_json::json!("secret5"),
         );
-        obj.insert("vault_token".to_string(), serde_json::json!("secret6"));
+        obj.insert(
+            "automation_webhook_secret".to_string(),
+            serde_json::json!("secret6"),
+        );
+        obj.insert("vault_token".to_string(), serde_json::json!("secret7"));
         mask_config_secrets(&mut obj);
         assert_eq!(obj.get("api_key").unwrap(), &serde_json::json!("***"));
         assert_eq!(obj.get("github_token").unwrap(), &serde_json::json!("***"));
@@ -242,6 +246,10 @@ mod tests {
             obj.get("github_webhook_secret").unwrap(),
             &serde_json::json!("***")
         );
+        assert_eq!(
+            obj.get("automation_webhook_secret").unwrap(),
+            &serde_json::json!("***")
+        );
         assert_eq!(obj.get("vault_token").unwrap(), &serde_json::json!("***"));
     }
 

src/server/api/admin.rs

@@ -132,6 +132,7 @@ pub(crate) fn mask_config_secrets(obj: &mut serde_json::Map<String, serde_json::
         "github_client_secret",
         "github_private_key",
         "github_webhook_secret",
+        "automation_webhook_secret",
         "vault_token",
     ] {
         if obj.get(*key).and_then(|v| v.as_str()).is_some() {

src/server/state.rs

@@ -32,6 +32,7 @@ pub(crate) use types::*;
 mod tests {
     use super::*;
     use crate::core::comment::{Category, FixEffort, Severity};
+    use mockito::Matcher;
     use std::path::PathBuf;
 
     #[test]
@@ -88,6 +89,75 @@ mod tests {
         assert!(json.contains("r-otel"), "payload must contain review_id");
     }
 
+    #[test]
+    fn test_serialize_review_event_webhook_payload_includes_delivery_metadata() {
+        let event = ReviewEventBuilder::new("r-webhook", "review.completed", "head", "gpt-4o")
+            .duration_ms(100)
+            .build();
+
+        let (delivery_id, body) = serialize_review_event_webhook_payload(&event).unwrap();
+        let payload: serde_json::Value = serde_json::from_str(&body).unwrap();
+
+        assert_eq!(payload["delivery_id"].as_str(), Some(delivery_id.as_str()));
+        assert!(payload["sent_at"].as_str().is_some());
+        assert_eq!(payload["review"]["review_id"].as_str(), Some("r-webhook"));
+        assert_eq!(
+            payload["review"]["event_type"].as_str(),
+            Some("review.completed")
+        );
+    }
+
+    #[tokio::test]
+    async fn test_send_review_event_webhook_noops_without_url() {
+        let event = ReviewEventBuilder::new("r-noop", "review.completed", "head", "gpt-4o").build();
+
+        let delivered = send_review_event_webhook(&reqwest::Client::new(), None, None, &event)
+            .await
+            .unwrap();
+
+        assert!(!delivered);
+    }
+
+    #[tokio::test]
+    async fn test_send_review_event_webhook_posts_signed_request() {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", "/hooks/reviews")
+            .match_header(
+                "content-type",
+                Matcher::Regex("application/json.*".to_string()),
+            )
+            .match_header("x-diffscope-event", "review.completed")
+            .match_header(
+                "x-diffscope-delivery",
+                Matcher::Regex("[0-9a-f-]{36}".to_string()),
+            )
+            .match_header(
+                "x-diffscope-signature-256",
+                Matcher::Regex("sha256=[0-9a-f]{64}".to_string()),
+            )
+            .match_body(Matcher::Regex(
+                r#""review_id":"r-hook".*"event_type":"review.completed""#.to_string(),
+            ))
+            .with_status(202)
+            .create_async()
+            .await;
+
+        let event = ReviewEventBuilder::new("r-hook", "review.completed", "head", "gpt-4o").build();
+
+        let delivered = send_review_event_webhook(
+            &reqwest::Client::new(),
+            Some(&format!("{}/hooks/reviews", server.url())),
+            Some("shared-secret"),
+            &event,
+        )
+        .await
+        .unwrap();
+
+        assert!(delivered);
+        mock.assert_async().await;
+    }
+
     #[test]
     fn test_review_event_builder_minimal() {
         let event = ReviewEventBuilder::new("r1", "review.completed", "head", "gpt-4o").build();

src/server/state/events.rs

@@ -1,4 +1,7 @@
 use super::*;
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+use uuid::Uuid;
 
 pub struct ReviewEventBuilder {
     event: ReviewEvent,
@@ -225,3 +228,104 @@ pub fn emit_wide_event(event: &ReviewEvent) {
         info!(target: "review.event.json", "{}", json);
     }
 }
+
+#[derive(Debug, Serialize)]
+struct AutomationWebhookPayload<'a> {
+    delivery_id: String,
+    sent_at: chrono::DateTime<chrono::Utc>,
+    review: &'a ReviewEvent,
+}
+
+pub(crate) fn dispatch_review_event_webhook(state: Arc<AppState>, event: ReviewEvent) {
+    tokio::spawn(async move {
+        let (webhook_url, webhook_secret) = {
+            let config = state.config.read().await;
+            (
+                config.automation.webhook_url.clone(),
+                config.automation.webhook_secret.clone(),
+            )
+        };
+
+        if let Err(err) = send_review_event_webhook(
+            &state.http_client,
+            webhook_url.as_deref(),
+            webhook_secret.as_deref(),
+            &event,
+        )
+        .await
+        {
+            warn!(
+                review_id = %event.review_id,
+                event_type = %event.event_type,
+                "Failed to deliver automation webhook: {}",
+                err
+            );
+        }
+    });
+}
+
+pub(crate) async fn send_review_event_webhook(
+    client: &reqwest::Client,
+    webhook_url: Option<&str>,
+    webhook_secret: Option<&str>,
+    event: &ReviewEvent,
+) -> anyhow::Result<bool> {
+    let Some(webhook_url) = webhook_url.map(str::trim).filter(|url| !url.is_empty()) else {
+        return Ok(false);
+    };
+
+    let (delivery_id, body) = serialize_review_event_webhook_payload(event)?;
+    let mut request = client
+        .post(webhook_url)
+        .header("Content-Type", "application/json")
+        .header("X-DiffScope-Event", &event.event_type)
+        .header("X-DiffScope-Delivery", &delivery_id)
+        .body(body.clone());
+
+    if let Some(secret) = webhook_secret
+        .map(str::trim)
+        .filter(|secret| !secret.is_empty())
+    {
+        request = request.header(
+            "X-DiffScope-Signature-256",
+            sign_review_event_webhook_body(secret, body.as_bytes())?,
+        );
+    }
+
+    let response = request.send().await?;
+    if !response.status().is_success() {
+        anyhow::bail!("automation webhook returned {}", response.status());
+    }
+
+    Ok(true)
+}
+
+pub(crate) fn serialize_review_event_webhook_payload(
+    event: &ReviewEvent,
+) -> anyhow::Result<(String, String)> {
+    let payload = AutomationWebhookPayload {
+        delivery_id: Uuid::new_v4().to_string(),
+        sent_at: chrono::Utc::now(),
+        review: event,
+    };
+    let delivery_id = payload.delivery_id.clone();
+    let body = serde_json::to_string(&payload)?;
+    Ok((delivery_id, body))
+}
+
+pub(crate) fn sign_review_event_webhook_body(secret: &str, body: &[u8]) -> anyhow::Result<String> {
+    let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes())?;
+    mac.update(body);
+    Ok(format!(
+        "sha256={}",
+        encode_hex(mac.finalize().into_bytes())
+    ))
+}
+
+fn encode_hex(bytes: impl AsRef<[u8]>) -> String {
+    bytes
+        .as_ref()
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect()
+}