feat: add ZITADEL Actions v3 webhook support

Add comprehensive support for handling ZITADEL Actions v3 webhooks with:
- Type-safe webhook handling with ActionHandler trait
- HMAC-SHA256 signature verification with timestamp validation
- Axum integration with webhook_handler function
- Builder pattern for ActionResponse construction
- Complete example showing job-specific claims
- Documentation and helper functions for common use cases

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: domenkozar

crates/zitadel/Cargo.toml

@@ -21,6 +21,9 @@ default = ["tls-roots"]
 ## Feature that enables support for the [actix framework](https://actix.rs/).
 actix = ["credentials", "oidc", "dep:actix-web"]
 
+## Feature that enables support for ZITADEL Actions v3 webhooks.
+actions-v3 = ["dep:async-trait", "dep:serde", "dep:serde_json", "dep:hmac", "dep:sha2", "dep:hex", "dep:thiserror"]
+
 api-common = ["dep:prost", "dep:prost-types", "dep:tonic", "dep:tonic-types", "dep:pbjson-types", "dep:zitadel-gen" ]
 
 ## The API feature enables all gRPC service clients to access the ZITADEL API.
@@ -102,6 +105,8 @@ axum-extra = { version = "0.10.0", optional = true, features = ["typed-header"]
 base64-compat = { version = "1", optional = true }
 custom_error = "1.9.2"
 document-features = { version = "0.2.8", optional = true }
+hex = { version = "0.4", optional = true }
+hmac = { version = "0.12", optional = true }
 jsonwebtoken = { version = "9.3.0", optional = true }
 moka = { version = "0.12.8", features = ["future"], optional = true }
 openidconnect = { version = "4.0.0", optional = true }
@@ -113,6 +118,8 @@ rocket = { version = "0.5.0", optional = true }
 serde = { version = "1.0.200", features = ["derive"], optional = true }
 serde_json = { version = "1.0.116", optional = true }
 serde_urlencoded = { version = "0.7.1", optional = true }
+sha2 = { version = "0.10", optional = true }
+thiserror = { version = "1.0", optional = true }
 time = { version = "0.3.36", optional = true }
 tokio = { version = "1.37.0", optional = true, features = [
   "macros",

crates/zitadel/examples/actions_v3_webhook.rs

@@ -0,0 +1,87 @@
+//! Example of handling ZITADEL Actions v3 webhooks
+//! 
+//! This example shows how to create a webhook handler for ZITADEL Actions v3
+//! that adds custom claims to tokens.
+
+use async_trait::async_trait;
+use axum::{routing::post, Router};
+use std::net::SocketAddr;
+use zitadel::actions::{ActionHandler, ActionRequest, ActionResponse};
+
+/// Custom webhook handler that adds job-specific claims
+struct JobLoggerHandler;
+
+#[derive(Debug, thiserror::Error)]
+#[error("Handler error")]
+struct HandlerError;
+
+#[async_trait]
+impl ActionHandler for JobLoggerHandler {
+    type Error = HandlerError;
+    
+    async fn complement_token(&self, req: &ActionRequest) -> Result<ActionResponse, Self::Error> {
+        // Check if this is a service account requesting a token
+        if let Some(service_account) = &req.service_account {
+            println!("Service account {} is requesting a token", service_account.client_id);
+            
+            // Look for job ID in the audience
+            if let Some(token) = &req.token {
+                for audience in &token.audience {
+                    if let Some(job_id) = audience.strip_prefix("logger:job:") {
+                        println!("Found job ID in audience: {}", job_id);
+                        
+                        // In a real application, you would verify the service account
+                        // has access to this job by checking your database
+                        
+                        return Ok(ActionResponse::default()
+                            .add_claim("urn:zitadel:iam:job:id", job_id)
+                            .add_claim("urn:zitadel:iam:job:permissions", vec!["log.read", "log.write"])
+                            .add_log(format!("Added job claims for job {}", job_id)));
+                    }
+                }
+            }
+        }
+        
+        // Return empty response if no custom claims needed
+        Ok(ActionResponse::default())
+    }
+    
+    async fn pre_userinfo_creation(&self, req: &ActionRequest) -> Result<ActionResponse, Self::Error> {
+        // You can also modify userinfo responses
+        if let Some(user) = &req.user {
+            println!("Modifying userinfo for user {}", user.id);
+            
+            return Ok(ActionResponse::default()
+                .add_claim("custom_userinfo", "value")
+                .add_metadata("last_webhook_call", chrono::Utc::now().to_rfc3339()));
+        }
+        
+        Ok(ActionResponse::default())
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    // Create the webhook handler
+    let handler = JobLoggerHandler;
+    
+    // Get webhook secret from environment
+    let webhook_secret = std::env::var("ZITADEL_WEBHOOK_SECRET")
+        .unwrap_or_else(|_| "test-secret".to_string());
+    
+    // Create the router with webhook endpoint
+    let app = Router::new()
+        .route(
+            "/webhook",
+            post(zitadel::axum::actions::webhook_handler(handler, webhook_secret))
+        );
+    
+    // Start the server
+    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
+    println!("Webhook server listening on {}", addr);
+    
+    axum::Server::bind(&addr)
+        .serve(app.into_make_service())
+        .await
+        .unwrap();
+}

crates/zitadel/src/actions/README.md

@@ -0,0 +1,97 @@
+# ZITADEL Actions v3 Webhook Support
+
+This module provides comprehensive support for handling ZITADEL Actions v3 webhooks in Rust applications.
+
+## Features
+
+- **Type-safe webhook handling**: Strongly typed request and response structures
+- **Signature verification**: HMAC-SHA256 signature verification with timestamp validation
+- **Framework integration**: Built-in support for Axum (with Actix and Rocket coming soon)
+- **Builder pattern**: Fluent API for constructing responses
+- **Async trait**: Define your webhook logic with async/await support
+
+## Usage
+
+### 1. Enable the feature
+
+Add the `actions-v3` feature to your `Cargo.toml`:
+
+```toml
+[dependencies]
+zitadel = { version = "0.1", features = ["actions-v3", "axum"] }
+```
+
+### 2. Implement the ActionHandler trait
+
+```rust
+use async_trait::async_trait;
+use zitadel::actions::{ActionHandler, ActionRequest, ActionResponse};
+
+struct MyHandler;
+
+#[async_trait]
+impl ActionHandler for MyHandler {
+    type Error = MyError;
+    
+    async fn complement_token(&self, req: &ActionRequest) -> Result<ActionResponse, Self::Error> {
+        // Add custom claims based on your business logic
+        Ok(ActionResponse::default()
+            .add_claim("custom_claim", "value")
+            .add_metadata("key", "value"))
+    }
+}
+```
+
+### 3. Set up the webhook endpoint
+
+```rust
+use axum::{routing::post, Router};
+use zitadel::axum::actions::webhook_handler;
+
+let app = Router::new()
+    .route("/webhook", post(webhook_handler(MyHandler, "your-webhook-secret")));
+```
+
+### 4. Configure ZITADEL Action
+
+In ZITADEL, create an Actions v3 with:
+- Trigger: `complement_token` (or other supported triggers)
+- Type: Webhook
+- URL: Your webhook endpoint
+- Secret: The same secret used in your handler
+
+## Supported Triggers
+
+- `complement_token`: Modify access token claims
+- `pre_userinfo_creation`: Modify userinfo endpoint response
+- `pre_access_token_creation`: Modify token before creation
+- `post_authentication`: React to successful authentication
+- `post_creation`: React to resource creation
+- `pre_creation`: Validate before resource creation
+
+## Security
+
+- Always use HTTPS in production
+- Keep your webhook secret secure
+- Implement proper error handling
+- Validate all inputs from the webhook payload
+- Use the built-in signature verification
+
+## Example: Job-Specific Claims
+
+```rust
+async fn complement_token(&self, req: &ActionRequest) -> Result<ActionResponse, Self::Error> {
+    if let Some(service_account) = &req.service_account {
+        // Extract job ID from audience
+        if let Some(job_id) = extract_job_id(&req) {
+            // Verify access in your database
+            if self.verify_access(&service_account.client_id, &job_id).await? {
+                return Ok(ActionResponse::default()
+                    .add_claim("job_id", job_id)
+                    .add_claim("permissions", vec!["read", "write"]));
+            }
+        }
+    }
+    Ok(ActionResponse::default())
+}
+```

crates/zitadel/src/actions/helpers.rs

@@ -0,0 +1,174 @@
+//! Helper functions and constants for ZITADEL Actions v3
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::actions::{ActionResponse, Claim, Metadata};
+
+/// Common ZITADEL claim keys
+pub mod claims {
+    /// Resource owner (organization) ID
+    pub const RESOURCE_OWNER_ID: &str = "urn:zitadel:iam:user:resourceowner:id";
+    
+    /// Resource owner name
+    pub const RESOURCE_OWNER_NAME: &str = "urn:zitadel:iam:user:resourceowner:name";
+    
+    /// Resource owner primary domain
+    pub const RESOURCE_OWNER_PRIMARY_DOMAIN: &str = "urn:zitadel:iam:user:resourceowner:primary_domain";
+    
+    /// Project roles
+    pub const PROJECT_ROLES: &str = "urn:zitadel:iam:org:project:roles";
+    
+    /// Project-specific roles format
+    pub const PROJECT_ROLES_FORMAT: &str = "urn:zitadel:iam:org:project:%s:roles";
+    
+    /// User metadata
+    pub const USER_METADATA: &str = "urn:zitadel:iam:user:metadata";
+    
+    /// Action log format
+    pub const ACTION_LOG_FORMAT: &str = "urn:zitadel:iam:action:%s:log";
+}
+
+impl ActionResponse {
+    /// Add a claim to the response
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use zitadel::actions::ActionResponse;
+    /// 
+    /// let response = ActionResponse::default()
+    ///     .add_claim("custom_claim", "value")
+    ///     .add_claim("roles", vec!["admin", "user"]);
+    /// ```
+    pub fn add_claim<K, V>(mut self, key: K, value: V) -> Self
+    where
+        K: Into<String>,
+        V: Serialize,
+    {
+        self.append_claims.push(Claim {
+            key: key.into(),
+            value: serde_json::to_value(value).unwrap_or(Value::Null),
+        });
+        self
+    }
+    
+    /// Add user metadata
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use zitadel::actions::ActionResponse;
+    /// 
+    /// let response = ActionResponse::default()
+    ///     .add_metadata("preference", "dark_mode")
+    ///     .add_metadata("last_login", "2024-01-01");
+    /// ```
+    pub fn add_metadata<K, V>(mut self, key: K, value: V) -> Self
+    where
+        K: Into<String>,
+        V: Serialize,
+    {
+        self.set_user_metadata.push(Metadata {
+            key: key.into(),
+            value: serde_json::to_value(value).unwrap_or(Value::Null),
+        });
+        self
+    }
+    
+    /// Add a log entry
+    /// 
+    /// Log entries are added to the token as an array under a special claim key.
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use zitadel::actions::ActionResponse;
+    /// 
+    /// let response = ActionResponse::default()
+    ///     .add_log("Custom claim added successfully")
+    ///     .add_log("User verified");
+    /// ```
+    pub fn add_log<S>(mut self, message: S) -> Self
+    where
+        S: Into<String>,
+    {
+        self.append_log_claims.push(message.into());
+        self
+    }
+    
+    /// Check if the response is empty (no modifications)
+    pub fn is_empty(&self) -> bool {
+        self.append_claims.is_empty()
+            && self.set_user_metadata.is_empty()
+            && self.append_log_claims.is_empty()
+    }
+    
+    /// Create a response with a single claim
+    pub fn with_claim<K, V>(key: K, value: V) -> Self
+    where
+        K: Into<String>,
+        V: Serialize,
+    {
+        Self::default().add_claim(key, value)
+    }
+    
+    /// Create a response with a single metadata entry
+    pub fn with_metadata<K, V>(key: K, value: V) -> Self
+    where
+        K: Into<String>,
+        V: Serialize,
+    {
+        Self::default().add_metadata(key, value)
+    }
+}
+
+/// Helper to create a claim
+pub fn claim<K, V>(key: K, value: V) -> Claim
+where
+    K: Into<String>,
+    V: Serialize,
+{
+    Claim {
+        key: key.into(),
+        value: serde_json::to_value(value).unwrap_or(Value::Null),
+    }
+}
+
+/// Helper to create metadata
+pub fn metadata<K, V>(key: K, value: V) -> Metadata
+where
+    K: Into<String>,
+    V: Serialize,
+{
+    Metadata {
+        key: key.into(),
+        value: serde_json::to_value(value).unwrap_or(Value::Null),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn test_response_builder() {
+        let response = ActionResponse::default()
+            .add_claim("test", "value")
+            .add_metadata("key", 123)
+            .add_log("Test log");
+        
+        assert_eq!(response.append_claims.len(), 1);
+        assert_eq!(response.set_user_metadata.len(), 1);
+        assert_eq!(response.append_log_claims.len(), 1);
+    }
+    
+    #[test]
+    fn test_empty_response() {
+        let response = ActionResponse::default();
+        assert!(response.is_empty());
+        
+        let response = response.add_claim("test", "value");
+        assert!(!response.is_empty());
+    }
+}