feat(api-integration): add Nango webhook handling (#3716)

* feat(api-integration): add webhook handling for Nango auth events

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* refactor: make nango_webhook_secret non-optional

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* refactor(nango): add verify_webhook_signature and use it from api-integration

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* chore: cleanup after moving webhook verification

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* fix(api-integration): require webhook secret in IntegrationConfig::new; adapt webhook signature verification to nango API

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* fix(api-integration): parse NangoAuthWebhook and commit lockfile

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* style: dprint format webhook route

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

* style(permissions): dprint fmt

Co-Authored-By: yujonglee <yujonglee.dev@gmail.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: yujonglee <yujonglee.dev@gmail.com>

Author: devin-ai-integration[bot]

Cargo.lock

@@ -297,6 +297,9 @@ objc2-event-kit = "0.3"
 objc2-foundation = "0.3"
 objc2-user-notifications = "0.3"
 
+hmac = "0.12"
+sha2 = "0.10"
+
 tokenizers = "0.21.4"
 whichlang = "0.1"
 

Cargo.toml

@@ -4,14 +4,20 @@ use std::sync::Arc;
 pub struct IntegrationConfig {
     pub nango_api_base: String,
     pub nango_api_key: String,
+    pub nango_webhook_secret: String,
     pub auth: Option<Arc<hypr_supabase_auth::SupabaseAuth>>,
 }
 
 impl IntegrationConfig {
-    pub fn new(nango_api_base: impl Into<String>, nango_api_key: impl Into<String>) -> Self {
+    pub fn new(
+        nango_api_base: impl Into<String>,
+        nango_api_key: impl Into<String>,
+        nango_webhook_secret: impl Into<String>,
+    ) -> Self {
         Self {
             nango_api_base: nango_api_base.into(),
             nango_api_key: nango_api_key.into(),
+            nango_webhook_secret: nango_webhook_secret.into(),
             auth: None,
         }
     }

crates/api-integration/src/config.rs

@@ -4,4 +4,5 @@ use serde::Deserialize;
 pub struct Env {
     pub nango_api_base: String,
     pub nango_api_key: String,
+    pub nango_webhook_secret: String,
 }

crates/api-integration/src/env.rs

@@ -7,5 +7,5 @@ mod state;
 pub use config::IntegrationConfig;
 pub use env::Env;
 pub use error::{IntegrationError, Result};
-pub use routes::{openapi, router};
+pub use routes::{WebhookResponse, openapi, router};
 pub use state::AppState;

crates/api-integration/src/lib.rs

@@ -1,20 +1,24 @@
 mod connect;
+mod webhook;
 
 use axum::{Router, routing::post};
 use utoipa::OpenApi;
 
 use crate::state::AppState;
 
 pub use connect::ConnectSessionResponse;
+pub use webhook::WebhookResponse;
 
 #[derive(OpenApi)]
 #[openapi(
     paths(
         connect::create_connect_session,
+        webhook::nango_webhook,
     ),
     components(
         schemas(
             ConnectSessionResponse,
+            WebhookResponse,
         )
     ),
     tags(
@@ -30,5 +34,6 @@ pub fn openapi() -> utoipa::openapi::OpenApi {
 pub fn router(state: AppState) -> Router {
     Router::new()
         .route("/connect-session", post(connect::create_connect_session))
+        .route("/webhook", post(webhook::nango_webhook))
         .with_state(state)
 }

crates/api-integration/src/routes/mod.rs

@@ -0,0 +1,58 @@
+use axum::{Json, extract::State, http::HeaderMap};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+use crate::error::{IntegrationError, Result};
+use crate::state::AppState;
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct WebhookResponse {
+    pub status: String,
+}
+
+#[utoipa::path(
+    post,
+    path = "/webhook",
+    responses(
+        (status = 200, description = "Webhook processed", body = WebhookResponse),
+        (status = 401, description = "Invalid signature"),
+        (status = 400, description = "Bad request"),
+    ),
+    tag = "integration",
+)]
+pub async fn nango_webhook(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+    body: String,
+) -> Result<Json<WebhookResponse>> {
+    let signature = headers
+        .get("x-nango-hmac-sha256")
+        .and_then(|h| h.to_str().ok())
+        .ok_or_else(|| IntegrationError::Auth("Missing X-Nango-Hmac-Sha256 header".to_string()))?;
+
+    let valid = hypr_nango::verify_webhook_signature(
+        &state.config.nango_webhook_secret,
+        body.as_bytes(),
+        signature,
+    );
+    if !valid {
+        return Err(IntegrationError::Auth(
+            "Invalid webhook signature".to_string(),
+        ));
+    }
+
+    let payload: hypr_nango::NangoAuthWebhook =
+        serde_json::from_str(&body).map_err(|e| IntegrationError::BadRequest(e.to_string()))?;
+
+    tracing::info!(
+        webhook_type = %payload.r#type,
+        operation = %payload.operation,
+        connection_id = %payload.connection_id,
+        end_user_id = %payload.end_user.end_user_id,
+        "nango webhook received"
+    );
+
+    Ok(Json(WebhookResponse {
+        status: "ok".to_string(),
+    }))
+}

crates/api-integration/src/routes/webhook.rs

@@ -5,16 +5,17 @@ edition = "2024"
 
 [dependencies]
 hex = "0.4"
-hmac = "0.12"
 reqwest = { workspace = true, features = ["json"] }
 schemars = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
-sha2 = "0.10"
 specta = { workspace = true, features = ["derive", "serde_json"] }
 strum = { workspace = true, features = ["derive"] }
 thiserror = { workspace = true }
 url = { workspace = true }
 
+hmac = { workspace = true }
+sha2 = { workspace = true }
+
 [dev-dependencies]
 tokio = { workspace = true, features = ["rt", "macros"] }

crates/nango/Cargo.toml

@@ -18,6 +18,8 @@ pub enum Error {
     InvalidApiBase,
     #[error("invalid url: cannot modify path segments")]
     InvalidUrl,
+    #[error("webhook signature error: {0}")]
+    WebhookSignature(String),
 }
 
 impl Serialize for Error {

crates/nango/src/error.rs

@@ -19,7 +19,6 @@ macro_rules! check {
     }};
 }
 
-
 #[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize, specta::Type)]
 #[serde(rename_all = "camelCase")]
 pub enum Permission {
@@ -117,7 +116,9 @@ impl<'a, R: tauri::Runtime, M: tauri::Manager<R>> Permissions<'a, R, M> {
         #[cfg(target_os = "macos")]
         {
             std::process::Command::new("open")
-                .arg("x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture")
+                .arg(
+                    "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
+                )
                 .spawn()?
                 .wait()?;
         }
@@ -129,7 +130,9 @@ impl<'a, R: tauri::Runtime, M: tauri::Manager<R>> Permissions<'a, R, M> {
         #[cfg(target_os = "macos")]
         {
             std::process::Command::new("open")
-                .arg("x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility")
+                .arg(
+                    "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",
+                )
                 .spawn()?
                 .wait()?;
         }
@@ -139,10 +142,9 @@ impl<'a, R: tauri::Runtime, M: tauri::Manager<R>> Permissions<'a, R, M> {
 
     async fn check_calendar(&self) -> Result<PermissionStatus, crate::Error> {
         #[cfg(target_os = "macos")]
-        return check!(
-            "calendar",
-            unsafe { EKEventStore::authorizationStatusForEntityType(EKEntityType::Event) }
-        );
+        return check!("calendar", unsafe {
+            EKEventStore::authorizationStatusForEntityType(EKEntityType::Event)
+        });
 
         #[cfg(not(target_os = "macos"))]
         {
@@ -152,10 +154,9 @@ impl<'a, R: tauri::Runtime, M: tauri::Manager<R>> Permissions<'a, R, M> {
 
     async fn check_contacts(&self) -> Result<PermissionStatus, crate::Error> {
         #[cfg(target_os = "macos")]
-        return check!(
-            "contacts",
-            unsafe { CNContactStore::authorizationStatusForEntityType(CNEntityType::Contacts) }
-        );
+        return check!("contacts", unsafe {
+            CNContactStore::authorizationStatusForEntityType(CNEntityType::Contacts)
+        });
 
         #[cfg(not(target_os = "macos"))]
         {
@@ -202,7 +203,10 @@ impl<'a, R: tauri::Runtime, M: tauri::Manager<R>> Permissions<'a, R, M> {
 
     async fn check_accessibility(&self) -> Result<PermissionStatus, crate::Error> {
         #[cfg(target_os = "macos")]
-        return check!("accessibility", macos_accessibility_client::accessibility::application_is_trusted());
+        return check!(
+            "accessibility",
+            macos_accessibility_client::accessibility::application_is_trusted()
+        );
 
         #[cfg(not(target_os = "macos"))]
         {
@@ -379,4 +383,3 @@ impl<R: tauri::Runtime, T: tauri::Manager<R>> PermissionsPluginExt<R> for T {
         }
     }
 }
-