Show number of pending webhooks in the warning section of the Account status (#4484)

* Show the number of pending webhooks in the warning section of the Account status

Author: diegocurbelo

changelog.txt

@@ -20,6 +20,7 @@
 * Update - Enhanced logging system with support for all log levels and improved context handling
 * Fix - Set default values for custom field options
 * Fix - Enforce rate limiter for failed add payment method attempts
+* Update - Add the number of pending webhooks to the Account status section
 
 = 9.6.0 - 2025-07-07 =
 * Fix - Register Express Checkout script before use to restore buttons on “order-pay” pages

includes/class-wc-stripe-webhook-handler.php

@@ -98,6 +98,8 @@ public function check_for_webhook() {
 			return;
 		}
 
+		WC_Stripe_Webhook_State::set_pending_webhooks_count( $event->pending_webhooks );
+
 		// Validate it to make sure it is legit.
 		$request_headers   = array_change_key_case( $this->get_request_headers(), CASE_UPPER );
 		$validation_result = $this->validate_request( $request_headers, $request_body );

includes/class-wc-stripe-webhook-state.php

@@ -15,11 +15,13 @@ class WC_Stripe_Webhook_State {
 	const OPTION_LIVE_LAST_SUCCESS_AT     = 'wc_stripe_wh_last_success_at';
 	const OPTION_LIVE_LAST_FAILURE_AT     = 'wc_stripe_wh_last_failure_at';
 	const OPTION_LIVE_LAST_ERROR          = 'wc_stripe_wh_last_error';
+	const OPTION_LIVE_PENDING_WEBHOOKS    = 'wc_stripe_wh_live_pending_webhooks';
 
 	const OPTION_TEST_MONITORING_BEGAN_AT = 'wc_stripe_wh_test_monitor_began_at';
 	const OPTION_TEST_LAST_SUCCESS_AT     = 'wc_stripe_wh_test_last_success_at';
 	const OPTION_TEST_LAST_FAILURE_AT     = 'wc_stripe_wh_test_last_failure_at';
 	const OPTION_TEST_LAST_ERROR          = 'wc_stripe_wh_test_last_error';
+	const OPTION_TEST_PENDING_WEBHOOKS    = 'wc_stripe_wh_test_pending_webhooks';
 
 	const VALIDATION_SUCCEEDED                 = 'validation_succeeded';
 	const VALIDATION_FAILED_EMPTY_HEADERS      = 'empty_headers';
@@ -57,13 +59,15 @@ public static function clear_state( $mode = 'all' ) {
 			delete_option( self::OPTION_LIVE_LAST_SUCCESS_AT );
 			delete_option( self::OPTION_LIVE_LAST_FAILURE_AT );
 			delete_option( self::OPTION_LIVE_LAST_ERROR );
+			delete_option( self::OPTION_LIVE_PENDING_WEBHOOKS );
 		}
 
 		if ( 'all' === $mode || 'test' === $mode ) {
 			delete_option( self::OPTION_TEST_MONITORING_BEGAN_AT );
 			delete_option( self::OPTION_TEST_LAST_SUCCESS_AT );
 			delete_option( self::OPTION_TEST_LAST_FAILURE_AT );
 			delete_option( self::OPTION_TEST_LAST_ERROR );
+			delete_option( self::OPTION_TEST_PENDING_WEBHOOKS );
 		}
 	}
 
@@ -227,6 +231,30 @@ public static function get_webhook_status_code() {
 		return 4;
 	}
 
+	/**
+	 * Sets the number of pending webhooks.
+	 *
+	 * @since 9.7.0
+	 *
+	 * @param int $pending_webhooks The number of pending webhooks.
+	 */
+	public static function set_pending_webhooks_count( $pending_webhooks ) {
+		$option = WC_Stripe_Mode::is_test() ? self::OPTION_TEST_PENDING_WEBHOOKS : self::OPTION_LIVE_PENDING_WEBHOOKS;
+		update_option( $option, $pending_webhooks );
+	}
+
+	/**
+	 * Gets the number of pending webhooks.
+	 *
+	 * @since 9.7.0
+	 *
+	 * @return int The number of pending webhooks.
+	 */
+	public static function get_pending_webhooks_count() {
+		$option = WC_Stripe_Mode::is_test() ? self::OPTION_TEST_PENDING_WEBHOOKS : self::OPTION_LIVE_PENDING_WEBHOOKS;
+		return get_option( $option, 0 );
+	}
+
 	/**
 	 * Gets the state of webhook processing in a human readable format.
 	 *
@@ -240,30 +268,35 @@ public static function get_webhook_status_message() {
 		$last_error          = self::get_last_error_reason();
 		$test_mode           = WC_Stripe_Mode::is_test();
 		$code                = self::get_webhook_status_code();
+		$pending_webhooks    = self::get_pending_webhooks_count();
 
 		$date_format = 'Y-m-d H:i:s e';
 
+		$message = '';
+
 		switch ( $code ) {
 			case 1: // Case 1 (Nominal case): Most recent = success
-				return sprintf(
+				$message = sprintf(
 					$test_mode ?
 						/* translators: 1) date and time of last webhook received, e.g. 2020-06-28 10:30:50 UTC */
 						__( 'The most recent test webhook, timestamped %s, was processed successfully.', 'woocommerce-gateway-stripe' ) :
 						/* translators: 1) date and time of last webhook received, e.g. 2020-06-28 10:30:50 UTC */
 						__( 'The most recent live webhook, timestamped %s, was processed successfully.', 'woocommerce-gateway-stripe' ),
 					gmdate( $date_format, $last_success_at )
 				);
+				break;
 			case 2: // Case 2: No webhooks received yet
-				return sprintf(
+				$message = sprintf(
 					$test_mode ?
 						/* translators: 1) date and time webhook monitoring began, e.g. 2020-06-28 10:30:50 UTC */
 						__( 'No test webhooks have been received since monitoring began at %s.', 'woocommerce-gateway-stripe' ) :
 						/* translators: 1) date and time webhook monitoring began, e.g. 2020-06-28 10:30:50 UTC */
 						__( 'No live webhooks have been received since monitoring began at %s.', 'woocommerce-gateway-stripe' ),
 					gmdate( $date_format, $monitoring_began_at )
 				);
+				break;
 			case 3: // Case 3: Failure after success
-				return sprintf(
+				$message = sprintf(
 					$test_mode ?
 						/*
 						 * translators: 1) date and time of last failed webhook e.g. 2020-06-28 10:30:50 UTC
@@ -279,10 +312,11 @@ public static function get_webhook_status_message() {
 						__( 'Warning: The most recent live webhook, received at %1$s, could not be processed. Reason: %2$s. (The last live webhook to process successfully was timestamped %3$s.)', 'woocommerce-gateway-stripe' ),
 					gmdate( $date_format, $last_failure_at ),
 					$last_error,
-					gmdate( $date_format, $last_success_at )
+					gmdate( $date_format, $last_success_at ),
 				);
+				break;
 			default: // Case 4: Failure with no prior success
-				return sprintf(
+				$message = sprintf(
 					$test_mode ?
 						/* translators: 1) date and time of last failed webhook e.g. 2020-06-28 10:30:50 UTC
 						 * translators: 2) reason webhook failed
@@ -296,9 +330,24 @@ public static function get_webhook_status_message() {
 						__( 'Warning: The most recent live webhook, received at %1$s, could not be processed. Reason: %2$s. (No live webhooks have been processed successfully since monitoring began at %3$s.)', 'woocommerce-gateway-stripe' ),
 					gmdate( $date_format, $last_failure_at ),
 					$last_error,
-					gmdate( $date_format, $monitoring_began_at )
+					gmdate( $date_format, $monitoring_began_at ),
 				);
 		}
+
+		if ( $pending_webhooks > 0 ) {
+			$message .= '. ' . sprintf(
+				/* translators: 1) number of pending webhooks */
+				_n(
+					'There is at least %d webhook pending.',
+					'There are approximately %d webhooks pending.',
+					$pending_webhooks,
+					'woocommerce-gateway-stripe'
+				),
+				$pending_webhooks
+			);
+		}
+
+		return $message;
 	}
 
 	/**

readme.txt

@@ -130,5 +130,6 @@ If you get stuck, you can ask for help in the [Plugin Forum](https://wordpress.o
 * Update - Enhanced logging system with support for all log levels and improved context handling
 * Fix - Set default values for custom field options
 * Fix - Enforce rate limiter for failed add payment method attempts
+* Update - Add the number of pending webhooks to the Account status section
 
 [See changelog for full details across versions](https://raw.githubusercontent.com/woocommerce/woocommerce-gateway-stripe/trunk/changelog.txt).

tests/phpunit/WC_Stripe_Webhook_State_Test.php

@@ -70,11 +70,13 @@ public function tear_down() {
 		delete_option( WC_Stripe_Webhook_State::OPTION_LIVE_LAST_SUCCESS_AT );
 		delete_option( WC_Stripe_Webhook_State::OPTION_LIVE_LAST_FAILURE_AT );
 		delete_option( WC_Stripe_Webhook_State::OPTION_LIVE_LAST_ERROR );
+		delete_option( WC_Stripe_Webhook_State::OPTION_LIVE_PENDING_WEBHOOKS );
 
 		delete_option( WC_Stripe_Webhook_State::OPTION_TEST_MONITORING_BEGAN_AT );
 		delete_option( WC_Stripe_Webhook_State::OPTION_TEST_LAST_SUCCESS_AT );
 		delete_option( WC_Stripe_Webhook_State::OPTION_TEST_LAST_FAILURE_AT );
 		delete_option( WC_Stripe_Webhook_State::OPTION_TEST_LAST_ERROR );
+		delete_option( WC_Stripe_Webhook_State::OPTION_TEST_PENDING_WEBHOOKS );
 
 		parent::tear_down();
 	}
@@ -127,9 +129,11 @@ private function process_webhook() {
 		if ( WC_Stripe_Webhook_State::VALIDATION_SUCCEEDED === $validation_result ) {
 			$notification = json_decode( $this->request_body );
 			WC_Stripe_Webhook_State::set_last_webhook_success_at( $notification->created );
+			WC_Stripe_Webhook_State::set_pending_webhooks_count( 0 );
 		} else {
 			WC_Stripe_Webhook_State::set_last_webhook_failure_at( time() );
 			WC_Stripe_Webhook_State::set_last_error_reason( $validation_result );
+			WC_Stripe_Webhook_State::set_pending_webhooks_count( 3 );
 		}
 	}
 
@@ -167,7 +171,7 @@ public function test_get_webhook_status_message_no_webhooks_received() {
 	// Case 3: Failure after success.
 	public function test_get_webhook_status_message_failure_after_success() {
 		$this->set_valid_request_data();
-		$expected_message = '/Warning: The most recent [mode] webhook, received at (.*), could not be processed. Reason: (.*) \(The last [mode] webhook to process successfully was timestamped/';
+		$expected_message = '/Warning: The most recent [mode] webhook, received at (.*), could not be processed. Reason: (.*) \(The last [mode] webhook to process successfully was timestamped (.*).\). There are approximately (\d+) webhooks pending./';
 		// Live
 		$this->set_testmode( 'no' );
 		// Process successful webhook.
@@ -193,7 +197,7 @@ public function test_get_webhook_status_message_failure_after_success() {
 	// Case 4: Failure with no prior success.
 	public function test_get_webhook_status_message_failure_with_no_prior_success() {
 		$this->set_valid_request_data();
-		$expected_message = '/Warning: The most recent [mode] webhook, received at (.*), could not be processed. Reason: (.*) \(No [mode] webhooks have been processed successfully since monitoring began at/';
+		$expected_message = '/Warning: The most recent [mode] webhook, received at (.*), could not be processed. Reason: (.*) \(No [mode] webhooks have been processed successfully since monitoring began at (.*).\). There are approximately (\d+) webhooks pending./';
 		// Live
 		$this->set_testmode( 'no' );
 		// Fail webhook.
@@ -208,6 +212,12 @@ public function test_get_webhook_status_message_failure_with_no_prior_success()
 		$this->process_webhook();
 		$message = WC_Stripe_Webhook_State::get_webhook_status_message();
 		$this->assertMatchesRegularExpression( str_replace( '[mode]', 'test', $expected_message ), $message );
+
+		// Test that when pending webhooks count is 1 the message is singular.
+		$expected_message = '/Warning: (.*).\). There is at least 1 webhook pending./';
+		WC_Stripe_Webhook_State::set_pending_webhooks_count( 1 );
+		$message = WC_Stripe_Webhook_State::get_webhook_status_message();
+		$this->assertMatchesRegularExpression( $expected_message, $message );
 	}
 
 	// Test failure reason: no error.