feat: add webhook support (blocking + notify) v0.2.6

Author: erdemgoksel

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.2.6
+
+Release date: 2026-03-26
+
+### Added
+
+- **Webhook support** (`webhooks` per `[server.NAME]`). Each server can now declare one or more webhooks that are called on every request **before** cache reads, ensuring access control is enforced even for cached responses.
+  - **`type = "blocking"`** — phantom-frame POSTs the request metadata to the webhook URL and awaits the response. A `2xx` reply allows the request to proceed; any non-`2xx` reply causes the same status code to be returned to the client immediately (the request is never forwarded to the backend or served from cache). A timeout or network error returns `503 Service Unavailable`.
+  - **`type = "notify"`** — the POST is dispatched as a fire-and-forget background task; the request always proceeds immediately regardless of the webhook outcome.
+  - `url` — the endpoint to POST to.
+  - `timeout_ms` — optional per-webhook timeout in milliseconds (default: `5000`). Only meaningful for `blocking` webhooks.
+  - Multiple webhooks per server are supported via the `[[server.NAME.webhooks]]` TOML array syntax. Blocking webhooks run sequentially; the first denial short-circuits the chain.
+  - Webhook POST body: `{ "method", "path", "query", "headers" }`. The request body is never consumed so latency overhead is minimal.
+- `serde_json` added as a dependency (used for webhook payload serialisation).
+
 ## v0.2.5
 
 Release date: 2026-03-26

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "phantom-frame"
-version = "0.2.5"
+version = "0.2.6"
 edition = "2021"
 authors = ["Erdem Göksel <erdem.goksel.dev@gmail.com>"]
 description = "A high-performance prerendering proxy engine with caching support"
@@ -16,6 +16,7 @@ categories = ["web-programming", "caching", "network-programming"]
 tokio = { version = "1.40", features = ["full"] }
 axum = "0.8.6"
 serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 toml = "0.9.8"
 reqwest = { version = "0.12", default-features = false, features = ["json"] }
 tower = "0.5"

examples/configs/basic.toml

@@ -79,6 +79,32 @@ enable_websocket = true
 # Optional: Override the directory used for filesystem-backed cache bodies
 # cache_directory = "./.phantom-frame-cache"
 
+# ── Webhooks ──────────────────────────────────────────────────────────────────
+#
+# Each [[server.NAME.webhooks]] entry defines one webhook for that server.
+# Webhooks fire on every request, BEFORE cache reads are attempted, so access
+# control is enforced even for cached responses.
+#
+# type = "blocking"  — phantom-frame POSTs request metadata to the URL and waits.
+#                      2xx response → request is allowed to continue.
+#                      Non-2xx response → the webhook's status code is returned to
+#                      the client and the request is not forwarded.
+#                      Timeout or connection error → 503 is returned to the client.
+#
+# type = "notify"    — phantom-frame fires a background POST and does not wait for
+#                      a response. The request always proceeds immediately.
+#
+# The POST body contains: method, path, query, headers (no request body).
+#
+# [[server.default.webhooks]]
+# url = "http://auth-service.internal/check"
+# type = "blocking"
+# timeout_ms = 3000    # optional, default 5000 ms
+#
+# [[server.default.webhooks]]
+# url = "http://logger.internal/log"
+# type = "notify"
+
 # ── Example: multi-server config (SSG frontend + dynamic API backend) ─────────
 #
 # [server.frontend]

src/config.rs

@@ -1,4 +1,4 @@
-use crate::{CacheStorageMode, CacheStrategy, CompressStrategy};
+use crate::{CacheStorageMode, CacheStrategy, CompressStrategy, WebhookConfig};
 use anyhow::{bail, Result};
 use serde::{
     de::{self, Visitor},
@@ -224,6 +224,11 @@ pub struct ServerConfig {
     /// Example: `"./apps/client"`
     #[serde(default)]
     pub execute_dir: Option<String>,
+
+    /// Webhooks called for every request before cache reads.
+    /// Blocking webhooks gate access; notify webhooks are fire-and-forget.
+    #[serde(default)]
+    pub webhooks: Vec<WebhookConfig>,
 }
 
 // ── defaults ────────────────────────────────────────────────────────────────
@@ -368,6 +373,7 @@ impl Default for ServerConfig {
             pre_generate_fallthrough: false,
             execute: None,
             execute_dir: None,
+            webhooks: vec![],
         }
     }
 }

src/lib.rs

@@ -136,6 +136,34 @@ impl std::fmt::Display for CacheStorageMode {
     }
 }
 
+/// The type of a webhook — controls whether the webhook gates access or just receives a notification.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum WebhookType {
+    /// The webhook call must complete with a 2xx response before the request is forwarded.
+    /// A non-2xx response (or a timeout / network error) causes the request to be denied.
+    Blocking,
+    /// The webhook call is dispatched in the background without blocking the request.
+    #[default]
+    Notify,
+}
+
+/// Configuration for a single webhook attached to a server.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct WebhookConfig {
+    /// The URL to POST the request metadata to.
+    pub url: String,
+
+    /// Whether this webhook is blocking (gates access) or notify (fire-and-forget).
+    #[serde(rename = "type", default)]
+    pub webhook_type: WebhookType,
+
+    /// Timeout in milliseconds for the webhook call (default: 5000 ms).
+    /// On timeout, a blocking webhook denies the request with 503.
+    #[serde(default)]
+    pub timeout_ms: Option<u64>,
+}
+
 /// Controls the operating mode of the proxy.
 #[derive(Clone, Debug, Default)]
 pub enum ProxyMode {
@@ -225,6 +253,10 @@ pub struct CreateProxyConfig {
 
     /// Controls the operating mode of the proxy (Dynamic vs PreGenerate/SSG).
     pub proxy_mode: ProxyMode,
+
+    /// Webhooks called for every request before cache reads.
+    /// Blocking webhooks gate access; notify webhooks are fire-and-forget.
+    pub webhooks: Vec<WebhookConfig>,
 }
 
 impl CreateProxyConfig {
@@ -250,6 +282,7 @@ impl CreateProxyConfig {
             cache_storage_mode: CacheStorageMode::Memory,
             cache_directory: None,
             proxy_mode: ProxyMode::Dynamic,
+            webhooks: vec![],
         }
     }
 
@@ -338,6 +371,13 @@ impl CreateProxyConfig {
         self.proxy_mode = mode;
         self
     }
+
+    /// Set the webhooks for this server.
+    /// Blocking webhooks gate access; notify webhooks are fire-and-forget.
+    pub fn with_webhooks(mut self, webhooks: Vec<WebhookConfig>) -> Self {
+        self.webhooks = webhooks;
+        self
+    }
 }
 
 /// The main library interface for using phantom-frame as a library

src/main.rs

@@ -81,6 +81,8 @@ async fn main() -> anyhow::Result<()> {
         };
         proxy_config = proxy_config.with_proxy_mode(proxy_mode);
 
+        proxy_config = proxy_config.with_webhooks(server_cfg.webhooks.clone());
+
         let (router, handle) = phantom_frame::create_proxy(proxy_config);
 
         tracing::info!(

src/proxy.rs

@@ -4,7 +4,7 @@ use crate::compression::{
     decompress_body, identity_acceptable,
 };
 use crate::path_matcher::should_cache_path;
-use crate::{CompressStrategy, CreateProxyConfig, ProxyMode};
+use crate::{CompressStrategy, CreateProxyConfig, ProxyMode, WebhookType};
 use axum::{
     body::Body,
     extract::Extension,
@@ -42,6 +42,60 @@ fn is_upgrade_request(headers: &HeaderMap) -> bool {
         || headers.contains_key(axum::http::header::UPGRADE)
 }
 
+/// Build the JSON payload sent to webhook endpoints.
+///
+/// Contains `method`, `path`, `query`, and `headers` (as a flat string-to-string
+/// map). The request body is intentionally excluded so that the caller never has
+/// to consume it before the payload is built.
+fn build_webhook_payload(
+    method: &str,
+    path: &str,
+    query: &str,
+    headers: &HeaderMap,
+) -> serde_json::Value {
+    let headers_map: serde_json::Map<String, serde_json::Value> = headers
+        .iter()
+        .filter_map(|(name, value)| {
+            value
+                .to_str()
+                .ok()
+                .map(|v| (name.as_str().to_string(), serde_json::Value::String(v.to_string())))
+        })
+        .collect();
+
+    serde_json::json!({
+        "method": method,
+        "path": path,
+        "query": query,
+        "headers": headers_map,
+    })
+}
+
+/// POST `payload` to `url`.
+///
+/// Returns:
+/// - `Ok(StatusCode)` — the HTTP status returned by the webhook server.
+/// - `Err(())` — timeout, connection error, or other transport failure.
+async fn call_webhook(
+    url: &str,
+    payload: &serde_json::Value,
+    timeout_ms: u64,
+) -> Result<StatusCode, ()> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_millis(timeout_ms))
+        .build()
+        .map_err(|_| ())?;
+
+    let response = client
+        .post(url)
+        .json(payload)
+        .send()
+        .await
+        .map_err(|_| ())?;
+
+    StatusCode::from_u16(response.status().as_u16()).map_err(|_| ())
+}
+
 /// Main proxy handler that serves prerendered content from cache
 /// or fetches from backend if not cached
 pub async fn proxy_handler(
@@ -101,6 +155,61 @@ pub async fn proxy_handler(
         return Err(StatusCode::METHOD_NOT_ALLOWED);
     }
 
+    // ── Webhook dispatch ────────────────────────────────────────────────────
+    // Webhooks fire before cache reads so that access control is enforced even
+    // for requests that would otherwise be served from the cache.
+    if !state.config.webhooks.is_empty() {
+        let payload = build_webhook_payload(method_str, path, query, &headers);
+
+        for webhook in &state.config.webhooks {
+            match webhook.webhook_type {
+                WebhookType::Notify => {
+                    // Fire-and-forget: spawn without awaiting.
+                    let url = webhook.url.clone();
+                    let payload_clone = payload.clone();
+                    let timeout_ms = webhook.timeout_ms.unwrap_or(5000);
+                    tokio::spawn(async move {
+                        if let Err(()) = call_webhook(&url, &payload_clone, timeout_ms).await {
+                            tracing::warn!("Notify webhook POST to '{}' failed", url);
+                        }
+                    });
+                }
+                WebhookType::Blocking => {
+                    let timeout_ms = webhook.timeout_ms.unwrap_or(5000);
+                    match call_webhook(&webhook.url, &payload, timeout_ms).await {
+                        Ok(status) if status.is_success() => {
+                            tracing::debug!(
+                                "Blocking webhook '{}' allowed {} {}",
+                                webhook.url,
+                                method_str,
+                                path
+                            );
+                        }
+                        Ok(status) => {
+                            tracing::warn!(
+                                "Blocking webhook '{}' denied {} {} with status {}",
+                                webhook.url,
+                                method_str,
+                                path,
+                                status
+                            );
+                            return Err(status);
+                        }
+                        Err(()) => {
+                            tracing::warn!(
+                                "Blocking webhook '{}' timed out or failed for {} {} — denying request",
+                                webhook.url,
+                                method_str,
+                                path
+                            );
+                            return Err(StatusCode::SERVICE_UNAVAILABLE);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     // Check if this path should be cached based on include/exclude patterns
     let should_cache = should_cache_path(
         method_str,