feat(platform): support platform-aware outgoing webhook delivery (#11643)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
Co-authored-by: Gnanasundari24 <118818938+Gnanasundari24@users.noreply.github.com>

Author: 4 people

api-reference/v1/openapi_spec_v1.json

@@ -20324,6 +20324,12 @@
             "example": "evt_018e31720d1b7a2b82677d3032cab959",
             "maxLength": 64
           },
+          "processor_merchant_id": {
+            "type": "string",
+            "description": "The identifier for the Processor Merchant Account.",
+            "nullable": true,
+            "maxLength": 64
+          },
           "created": {
             "type": "string",
             "format": "date-time",
@@ -26754,7 +26760,7 @@
         "properties": {
           "merchant_id": {
             "type": "string",
-            "description": "The merchant id of the merchant"
+            "description": "The provider merchant id (platform/business owner)"
           },
           "event_id": {
             "type": "string",
@@ -26770,6 +26776,11 @@
             "type": "string",
             "format": "date-time",
             "description": "The time at which webhook was sent"
+          },
+          "processor_merchant_id": {
+            "type": "string",
+            "description": "The merchant id of the merchant account whose connector credentials are used for payment processing",
+            "nullable": true
           }
         }
       },

api-reference/v2/openapi_spec_v2.json

@@ -13948,6 +13948,12 @@
             "example": "evt_018e31720d1b7a2b82677d3032cab959",
             "maxLength": 64
           },
+          "processor_merchant_id": {
+            "type": "string",
+            "description": "The identifier for the Processor Merchant Account.",
+            "nullable": true,
+            "maxLength": 64
+          },
           "created": {
             "type": "string",
             "format": "date-time",
@@ -19784,7 +19790,7 @@
         "properties": {
           "merchant_id": {
             "type": "string",
-            "description": "The merchant id of the merchant"
+            "description": "The provider merchant id (platform/business owner)"
           },
           "event_id": {
             "type": "string",
@@ -19800,6 +19806,11 @@
             "type": "string",
             "format": "date-time",
             "description": "The time at which webhook was sent"
+          },
+          "processor_merchant_id": {
+            "type": "string",
+            "description": "The merchant id of the merchant account whose connector credentials are used for payment processing",
+            "nullable": true
           }
         }
       },

crates/analytics/docs/clickhouse/scripts/outgoing_webhook_events.sql

@@ -16,7 +16,9 @@ CREATE TABLE outgoing_webhook_events_queue (
     `initial_attempt_id` Nullable(String),
     `status_code` Nullable(UInt16),
     `delivery_attempt` LowCardinality(String),
-    `created_at_timestamp` DateTime64(3)
+    `created_at_timestamp` DateTime64(3),
+    `processor_merchant_id` Nullable(String),
+    `initiator_merchant_id` Nullable(String)
 ) ENGINE = Kafka SETTINGS kafka_broker_list = 'kafka0:29092',
 kafka_topic_list = 'hyperswitch-outgoing-webhook-events',
 kafka_group_name = 'hyper',
@@ -43,6 +45,8 @@ CREATE TABLE outgoing_webhook_events (
     `delivery_attempt` LowCardinality(String),
     `created_at` DateTime64(3),
     `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4),
+    `processor_merchant_id` Nullable(String),
+    `initiator_merchant_id` Nullable(String),
     INDEX eventIndex event_type TYPE bloom_filter GRANULARITY 1,
     INDEX webhookeventIndex outgoing_webhook_event_type TYPE bloom_filter GRANULARITY 1
 ) ENGINE = MergeTree PARTITION BY toStartOfDay(created_at)
@@ -73,7 +77,9 @@ CREATE TABLE outgoing_webhook_events_audit (
     `status_code` Nullable(UInt16),
     `delivery_attempt` LowCardinality(String),
     `created_at` DateTime64(3),
-    `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4)
+    `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4),
+    `processor_merchant_id` Nullable(String),
+    `initiator_merchant_id` Nullable(String)
 ) ENGINE = MergeTree PARTITION BY merchant_id
 ORDER BY
     (merchant_id, payment_id) TTL inserted_at + toIntervalMonth(18) SETTINGS index_granularity = 8192;
@@ -118,7 +124,9 @@ CREATE MATERIALIZED VIEW outgoing_webhook_events_mv TO outgoing_webhook_events (
     `status_code` Nullable(UInt16),
     `delivery_attempt` LowCardinality(String),
     `created_at` DateTime64(3),
-    `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4)
+    `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4),
+    `processor_merchant_id` Nullable(String),
+    `initiator_merchant_id` Nullable(String)
 ) AS
 SELECT
     merchant_id,
@@ -139,7 +147,9 @@ SELECT
     status_code,
     delivery_attempt,
     created_at_timestamp AS created_at,
-    now() AS inserted_at
+    now() AS inserted_at,
+    processor_merchant_id,
+    initiator_merchant_id
 FROM
     outgoing_webhook_events_queue
 WHERE
@@ -163,7 +173,9 @@ CREATE MATERIALIZED VIEW outgoing_webhook_events_audit_mv TO outgoing_webhook_ev
     `status_code` Nullable(UInt16),
     `delivery_attempt` LowCardinality(String),
     `created_at` DateTime64(3),
-    `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4)
+    `inserted_at` DateTime DEFAULT now() CODEC(T64, LZ4),
+    `processor_merchant_id` Nullable(String),
+    `initiator_merchant_id` Nullable(String)
 ) AS
 SELECT
     merchant_id,
@@ -183,7 +195,9 @@ SELECT
     status_code,
     delivery_attempt,
     created_at_timestamp AS created_at,
-    now() AS inserted_at
+    now() AS inserted_at,
+    processor_merchant_id,
+    initiator_merchant_id
 FROM
     outgoing_webhook_events_queue
 WHERE
@@ -249,4 +263,4 @@ SELECT
 FROM
     outgoing_webhook_events_queue
 WHERE
-    length(_error) > 0;
+    length(_error) > 0;

crates/analytics/src/outgoing_webhook_event/events.rs

@@ -97,6 +97,7 @@ pub struct OutgoingWebhookLogsResult {
     pub content: Option<String>,
     pub is_error: bool,
     pub error: Option<String>,
+    pub initiator_merchant_id: Option<common_utils::id_type::MerchantId>,
     #[serde(with = "common_utils::custom_serde::iso8601")]
     pub created_at: PrimitiveDateTime,
 }

crates/api_models/src/webhook_events.rs

@@ -95,6 +95,10 @@ pub struct EventListItemResponse {
     #[schema(max_length = 64, example = "evt_018e31720d1b7a2b82677d3032cab959")]
     pub initial_attempt_id: String,
 
+    /// The identifier for the Processor Merchant Account.
+    #[schema(max_length = 64, value_type = Option<String>)]
+    pub processor_merchant_id: Option<common_utils::id_type::MerchantId>,
+
     /// Time at which the event was created.
     #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(with = "common_utils::custom_serde::iso8601")]

crates/api_models/src/webhooks.rs

@@ -443,7 +443,7 @@ pub struct PayoutWebhookUpdate {
 
 #[derive(Debug, Serialize, ToSchema)]
 pub struct OutgoingWebhook {
-    /// The merchant id of the merchant
+    /// The provider merchant id (platform/business owner)
     #[schema(value_type = String)]
     pub merchant_id: common_utils::id_type::MerchantId,
 
@@ -460,6 +460,10 @@ pub struct OutgoingWebhook {
     /// The time at which webhook was sent
     #[serde(default, with = "custom_serde::iso8601")]
     pub timestamp: PrimitiveDateTime,
+
+    /// The merchant id of the merchant account whose connector credentials are used for payment processing
+    #[schema(value_type = Option<String>)]
+    pub processor_merchant_id: Option<common_utils::id_type::MerchantId>,
 }
 
 #[derive(Debug, Clone, Serialize, ToSchema)]

crates/common_utils/src/types.rs

@@ -1459,6 +1459,19 @@ impl_enum_str!(
     }
 );
 
+impl CreatedBy {
+    /// Returns `true` if the creator is the provider (platform) merchant, i.e. an API-triggered
+    /// creation whose `merchant_id` matches `provider_merchant_id`.
+    pub fn is_provider_initiated(&self, provider_merchant_id: &id_type::MerchantId) -> bool {
+        match self {
+            Self::Api { merchant_id } => id_type::MerchantId::wrap(merchant_id.clone())
+                .map(|parsed_merchant_id| parsed_merchant_id == *provider_merchant_id)
+                .unwrap_or_default(),
+            Self::Jwt { .. } | Self::Invalid | Self::EmbeddedToken { .. } => false,
+        }
+    }
+}
+
 /// Trait for enums created with `impl_enum_str!` macro that have an `Invalid` variant.
 /// This trait allows generic functions to check if a parsed enum value is invalid.
 pub trait HasInvalidVariant {

crates/diesel_models/src/events.rs

@@ -27,6 +27,8 @@ pub struct EventNew {
     pub delivery_attempt: Option<storage_enums::WebhookDeliveryAttempt>,
     pub metadata: Option<EventMetadata>,
     pub is_overall_delivery_successful: Option<bool>,
+    pub processor_merchant_id: Option<common_utils::id_type::MerchantId>,
+    pub initiator_merchant_id: Option<common_utils::id_type::MerchantId>,
 }
 
 #[derive(Clone, Debug, Default, AsChangeset, router_derive::DebugAsDisplay)]
@@ -60,6 +62,8 @@ pub struct Event {
     pub delivery_attempt: Option<storage_enums::WebhookDeliveryAttempt>,
     pub metadata: Option<EventMetadata>,
     pub is_overall_delivery_successful: Option<bool>,
+    pub processor_merchant_id: Option<common_utils::id_type::MerchantId>,
+    pub initiator_merchant_id: Option<common_utils::id_type::MerchantId>,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize, AsExpression, diesel::FromSqlRow)]