feat(connector): Add support for passive churn recovery webhooks #7109

srujanchikke · 2025-01-27T05:44:50Z

Type of Change

Description

Recovery Incoming Webhooks service :
Consume incoming webhooks of billing platforms to schedule revenue recovery retries in hs.
Endpoint :
v2/webhooks/revenue_recovery/{{profile_id}}/{{merchant_connector_account_id}}
Authentication :
Source verification.
Method :
POST
Request :
Accepts connector specific requests , unified fields that we are going to consume and verified across billing platforms(Chargebee, Recurly, Stripe Billing).
Response :
They expect us to send 200 back.

DB changes :

Triggered by : Flag to find out whether an attempt was created external or internal. Possible enums of triggered_by EXTERNAL/ INTERNAL.
Payment attempt

feature_metadata{
revenue_recovery :  {
triggered_by : TriggeredBy
}
}

triggered_by : Flag to find out whether an attempt was created external or internal. Possible enums of triggered_by EXTERNAL/ INTERNAL

Flow

We receive invoice and transactional related incoming webhooks from billing connectors(ex: chargebee).
Verify the source with source verification logic using incoming webhook trait.
Fetch the intent using merchant reference id(Invoice id), if not found create new payment intent for the invoice.
Fetch the attempt if event is transactional event, if not found record new attempt against the payment intent .
Based on triggered_by and event type decide what actions needs to be taken for the webhook

Note: Only handler functions of payments core are called in webhooks flow to make revenue recovery flow modular. No direct DB call is made in recovery incoming webhook flow to payments(intent/attempt) table.

why do we need attempt.triggered_by and event type to take the decision?

Recovery event types : There can be 4 types of events that we consume from billing connector.
- Payment Failure, payment success, payment pending, Invoice cancel
  Based on event we take the action but we need to triggered by to know whether it was created by Hyperswitch or External system.
Recovery Actions :

/// type of action that needs to taken after consuming recovery payload
RecoveryAction {
    /// Stops the process tracker and update the payment intent.
    CancelInvoice,
    /// Records the external transaction against payment intent.
    ScheduleFailedPayment,
    /// Records the external payment and stops the internal process tracker.
    SuccessPaymentExternal,
    /// Pending payments from billing processor.
    PendingPayment,
    /// No action required.
    NoAction,
    /// Invalid event has been received.
    InvalidAction,
}

Mapping between (event, triggered_by) and Actions

IncomingWebhookEvent::RecoveryPaymentFailure => match attempt_triggered_by {
                Some(TriggeredBy::Internal) => RecoveryAction::NoAction,
                Some(TriggeredBy::External) | None => RecoveryAction::ScheduleFailedPayment,
            },
            IncomingWebhookEvent::RecoveryPaymentSuccess => match attempt_triggered_by {
                Some(TriggeredBy::Internal) => RecoveryAction::NoAction,
                Some(TriggeredBy::External) | None => RecoveryAction::SuccessPaymentExternal,
            },
            IncomingWebhookEvent::RecoveryPaymentPending => RecoveryAction::PendingPayment,
            IncomingWebhookEvent::RecoveryInvoiceCancel => RecoveryAction::CancelInvoice,

Note : Pending Task From this PR

charegebee Webhooks implementations- feat(connector): Add support for chargebee recovery webhooks #7110
Record Attempt internal - feat(core): Add record attempt operation for revenue recovery webhooks #7236

Additional Changes

This PR modifies the API contract
This PR modifies the database schema
This PR modifies application configuration/environment variables

Motivation and Context

Cannot test this flow, will be tested once #7236 and #7110 are merged.

Checklist

I formatted the code cargo +nightly fmt --all
I addressed lints thrown by cargo clippy
I reviewed the submitted code
I added unit tests for my changes where possible

semanticdiff-com · 2025-01-27T05:44:53Z

Review changes with

Changed Files

File	Status
crates/router/src/routes/lock_utils.rs	82% smaller
crates/openapi/src/openapi.rs	28% smaller
crates/router/src/core/payments.rs	25% smaller
crates/openapi/src/openapi_v2.rs	9% smaller
api-reference-v2/openapi_spec.json	9% smaller
crates/common_utils/src/ext_traits.rs	4% smaller
crates/api_models/src/payments.rs	1% smaller
api-reference/openapi_spec.json	0% smaller
crates/api_models/Cargo.toml	Unsupported file format
crates/api_models/src/webhooks.rs	0% smaller
crates/common_enums/src/enums.rs	0% smaller
crates/diesel_models/src/payment_attempt.rs	0% smaller
crates/diesel_models/src/schema_v2.rs	0% smaller
crates/hyperswitch_domain_models/Cargo.toml	Unsupported file format
crates/hyperswitch_domain_models/src/lib.rs	0% smaller
crates/hyperswitch_domain_models/src/payments/payment_attempt.rs	0% smaller
crates/hyperswitch_domain_models/src/revenue_recovery.rs	0% smaller
crates/hyperswitch_interfaces/Cargo.toml	Unsupported file format
crates/hyperswitch_interfaces/src/webhooks.rs	0% smaller
crates/router/Cargo.toml	Unsupported file format
crates/router/src/core/errors.rs	0% smaller
crates/router/src/core/payments/transformers.rs	0% smaller
crates/router/src/core/webhooks.rs	0% smaller
crates/router/src/core/webhooks/incoming_v2.rs	0% smaller
crates/router/src/core/webhooks/recovery_incoming.rs	0% smaller
crates/router/src/routes.rs	0% smaller
crates/router/src/routes/app.rs	0% smaller
crates/router/src/routes/recovery_webhooks.rs	0% smaller
crates/router/src/services/connector_integration_interface.rs	Unsupported file format
crates/router_env/src/logger/types.rs	0% smaller
v2_migrations/2025-01-17-042122_add_feature_metadata_in_payment_attempt/down.sql	Unsupported file format
v2_migrations/2025-01-17-042122_add_feature_metadata_in_payment_attempt/up.sql	Unsupported file format

sai-harsha-vardhan · 2025-02-19T17:28:00Z

crates/api_models/src/webhooks.rs

+#[cfg(all(feature = "v2", feature = "revenue_recovery"))]
+impl IncomingWebhookEvent {
+    pub fn is_recovery_transaction_event(&self) -> bool {
+        match self {


nit: can use matches!

sai-harsha-vardhan · 2025-02-19T17:30:27Z

crates/common_enums/src/enums.rs

+#[strum(serialize_all = "snake_case")]
+#[serde(rename_all = "snake_case")]
+pub enum TriggeredBy {
+    /// Denotes payment attempt is been created by hyperswitch system.


nit: prefer not refer hyperswitch in codebase

sai-harsha-vardhan · 2025-02-19T17:41:33Z

crates/hyperswitch_domain_models/src/revenue_recovery.rs

+    /// merchant reference id at billing connector. ex: invoice_id
+    pub merchant_reference_id: common_utils::id_type::PaymentReferenceId,
+    /// transaction id reference at payment connector
+    pub connector_transaction_id: Option<String>,


Can we please use ConnectorTransactionId domain type here?

sai-harsha-vardhan · 2025-02-19T17:42:33Z

crates/hyperswitch_domain_models/src/revenue_recovery.rs

+    /// error message sent by billing connector.
+    pub error_message: Option<String>,
+    /// mandate token at payment processor end.
+    pub processor_payment_token: Option<String>,


mandate token, is more of processor_payment_method_token right? not payment token?

sai-harsha-vardhan · 2025-02-19T17:44:17Z

crates/hyperswitch_domain_models/src/revenue_recovery.rs

+    /// customer id at payment connector for which mandate is attached.
+    pub connector_customer_id: Option<String>,
+    /// payment merchant connnector account reference id at billing connector.
+    pub connector_account_reference_id: Option<String>,


what exactly is merchant connnector account reference id?

Payment gateway identifier id at billing processor. Add the same comment.

sai-harsha-vardhan · 2025-02-19T18:15:52Z

crates/router/src/core/webhooks/recovery_incoming.rs

+            {
+                Ok(None)
+            }
+            Ok(_) | Err(_) => Err(errors::RevenueRecoveryError::PaymentIntentFetchFailed)


We should be logging Err(err) here, and any other Ok() response is unexpected

sai-harsha-vardhan · 2025-02-19T18:19:52Z

crates/router/src/core/webhooks/recovery_incoming.rs

+            hyperswitch_domain_models::payments::HeaderPayload::default(),
+        ))
+        .await;
+        router_env::logger::info!(?attempt_response);


Are these loggers required? If yes, please add relevant keys if not there's no use of this loggers

sai-harsha-vardhan · 2025-02-19T18:20:21Z

crates/router/src/core/webhooks/recovery_incoming.rs

+                });
+                Ok(payment_attempt)
+            }
+            Ok(_) | Err(_) => Err(errors::RevenueRecoveryError::PaymentAttemptFetchFailed)


sai-harsha-vardhan · 2025-02-19T18:21:54Z

crates/router/src/routes/app.rs

+        #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+        {
+            route = route.service(
+                web::resource("/recovery/{merchant_id}/{profile_id}/{connector_id}").route(


preferably stricter routes should be on top of generic routes

This not required here since, since number of parameters vary for payment webhooks and recovery webhooks

sai-harsha-vardhan · 2025-02-19T18:23:09Z

crates/router/src/routes/lock_utils.rs

@@ -310,6 +310,7 @@ impl From<Flow> for ApiIdentifier {
            Flow::RetrievePollStatus => Self::Poll,

            Flow::FeatureMatrix => Self::Documentation,
+            Flow::RecoveryIncomingWebhookReceive => Self::Webhooks,


nit: can you move this to existing webhooks match statement instead

Chikke Srujan and others added 9 commits January 15, 2025 09:27

add template code for chargebee

57b6b86

merge main

d27700e

chore: run formatter

b3908c0

add recovery incoming webhooks support

ff41480

add feature metadata queries

d5d14fe

clippy fix

dcc6b1f

Merge branch 'main' into chargebee_integration

55f3018

merge main

7f05e1a

chore: run formatter

251f492

hyperswitch-bot bot added the M-database-changes Metadata: This PR involves database schema changes label Jan 27, 2025

srujanchikke and others added 2 commits January 27, 2025 11:15

Merge branch 'chargebee_integration' into recovery_webhooks

9619365

chore: run formatter

6866eaf

Base automatically changed from chargebee_integration to main January 29, 2025 11:47

Merge branch 'main' into recovery_webhooks

7994d71

srujanchikke self-assigned this Feb 5, 2025

Chikke Srujan and others added 13 commits February 10, 2025 20:03

Merge branch 'main' into recovery_webhooks

b0699a3

Merge branch 'main' into recovery_webhooks

f92ee73

Merge branch 'main' into recovery_webhooks

ef12ef3

Merge branch 'main' into recovery_webhooks

aff2350

payment attempt feature metadata refactor

4203413

Merge branch 'main' into recovery_webhooks

1c60b72

chore: run formatter

6e5cd99

clippy fix

a75741a

chore: run formatter

d22da80

minor refactor

9b3cd47

Merge branch 'main' into recovery_webhooks

13d6e91

change feature flag name

f63cb5e

chore: run formatter

e22e24b

srujanchikke marked this pull request as ready for review February 18, 2025 05:55

Chikke Srujan and others added 5 commits February 19, 2025 16:45

resolve comments

61aee66

clippy fix

1e8eb88

resolve comments

6cc5d2d

clippy fix

51efe70

chore: run formatter

be03d4c

jarnura previously approved these changes Feb 19, 2025

View reviewed changes

sai-harsha-vardhan reviewed Feb 19, 2025

View reviewed changes

Chikke Srujan added 2 commits February 20, 2025 14:19

resolve comments

5353ae6

revert toml

f333fa0

srujanchikke dismissed jarnura’s stale review via f333fa0 February 20, 2025 08:49

hyperswitch-bot bot and others added 9 commits February 20, 2025 08:50

chore: run formatter

488563f

Merge branch 'main' into recovery_webhooks

675c5c5

open api fix

ced7309

docs(openapi): re-generate OpenAPI specification

03f4ad4

add v1 feature flag

ee8bb09

Merge branch 'main' into recovery_webhooks

7a6dd94

resolve comments

05a11dd

clippy fix

4a5152a

Merge branch 'main' into recovery_webhooks

abaf2c3

jarnura approved these changes Feb 21, 2025

View reviewed changes

sai-harsha-vardhan approved these changes Feb 21, 2025

View reviewed changes

likhinbopanna enabled auto-merge February 21, 2025 09:44

likhinbopanna added this pull request to the merge queue Feb 21, 2025

github-merge-queue bot removed this pull request from the merge queue due to no response for status checks Feb 21, 2025

Merge branch 'main' into recovery_webhooks

5c58cab

likhinbopanna enabled auto-merge February 22, 2025 18:40

likhinbopanna added this pull request to the merge queue Feb 22, 2025

Merged via the queue into main with commit 0688972 Feb 22, 2025
16 of 20 checks passed

likhinbopanna deleted the recovery_webhooks branch February 22, 2025 21:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(connector): Add support for passive churn recovery webhooks #7109

feat(connector): Add support for passive churn recovery webhooks #7109

Uh oh!

srujanchikke commented Jan 27, 2025 •

edited

Loading

Uh oh!

semanticdiff-com bot commented Jan 27, 2025 •

edited

Loading

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

srujanchikke Feb 20, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

srujanchikke Feb 20, 2025

Uh oh!

sai-harsha-vardhan Feb 19, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat(connector): Add support for passive churn recovery webhooks #7109

feat(connector): Add support for passive churn recovery webhooks #7109

Uh oh!

Conversation

srujanchikke commented Jan 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Description

Additional Changes

Motivation and Context

Checklist

Uh oh!

semanticdiff-com bot commented Jan 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

srujanchikke commented Jan 27, 2025 •

edited

Loading

semanticdiff-com bot commented Jan 27, 2025 •

edited

Loading