feature: add webhook sample logic

src/OffSiteGateway/Gateway/OffSiteCheckoutPageSimulation.php

@@ -56,9 +56,8 @@ private function loadOffSiteGatewaySimulationMarkup()
             .container {
                 font-family: "Open Sans", Helvetica, Arial, sans-serif;
                 max-width: 800px;
-                margin: 100px auto;
+                margin: 60px auto;
             }
-
             a {
                 font-size: 1.5rem;
             }
@@ -81,6 +80,21 @@ private function loadOffSiteGatewaySimulationMarkup()
             <p>
                 <strong>Click on the links below to simulate off-site gateway actions:</strong>
             </p>
+            <a style="color:#696969;font-weight:bold;font-size: 1.2rem" target="_blank" href="<?php
+            echo add_query_arg([
+                'notification_type' => 'one-time',
+                'payment_status' => 'complete',
+                'payment_id' => $_GET['gatewayPaymentId'],
+                'merchant_payment_id' => $_GET['merchantPaymentId'],
+            ],
+                $_GET['webhookUrl']) ?>">
+                Send Webhook Notification To Change Donation Status To Complete ⭷
+            </a>
+            <p>
+                🛈 Some gateways send webhook notifications to change the transaction status a few hours after the
+                payment process is finished, and others can send them even before the user is redirected back to the
+                referrer's website — the action above simulates this last scenario.
+            </p>
             <a style="color:green;font-weight: bold;" href="<?php
             echo $_GET['returnUrl'] ?>">Success Payment</a> | <a style="color:red;font-weight: bold;" href="<?php
             echo $_GET['cancelUrl'] ?>">Canceled Payment</a>

src/OffSiteGateway/Gateway/OffSiteGateway.php

@@ -189,6 +189,7 @@ public function getPaymentParameters(Donation $donation, $gatewayData): array
     {
         return [
             'gatewayPaymentId' => $donation->gatewayTransactionId,
+            'merchantPaymentId' => $donation->id,
             'amount' => [
                 'value' => $donation->amount->formatToDecimal(),
                 'currency' => $donation->amount->getCurrency()->getCode(),
@@ -258,7 +259,7 @@ protected function handleCanceledPaymentReturn(array $queryParams): RedirectResp
     protected function webhookNotificationsListener()
     {
         try {
-            $webhookNotification = OffSiteGatewayWebhookNotification::fromRequest($_REQUEST);
+            $webhookNotification = OffSiteGatewayWebhookNotification::fromRequest(give_clean($_REQUEST));
             give(OffSiteGatewaysWebhookNotificationHandler::class)($webhookNotification);
         } catch (Exception $e) {
             esc_html_e('Off-site gateway Webhook Notification failed.', 'ADDON_TEXTDOMAIN');

src/OffSiteGateway/Webhooks/OffSiteGatewaysWebhookNotificationHandler.php

@@ -4,6 +4,7 @@
 
 use Give\Framework\Support\Facades\ActionScheduler\AsBackgroundJobs;
 use GiveAddon\OffSiteGateway\DataTransferObjects\OffSiteGatewayWebhookNotification;
+use GiveAddon\OffSiteGateway\Gateway\OffSiteGateway;
 
 /**
  * @unreleased
@@ -22,7 +23,7 @@ public function __invoke(OffSiteGatewayWebhookNotification $webhookNotification)
          *
          * @param OffSiteGatewayWebhookNotification $webhookNotification
          */
-        do_action("givewp_off-site_gateway_sample_webhook_notification_handler", $webhookNotification);
+        do_action('givewp_' . OffSiteGateway::id() . '_webhook_notification_handler', $webhookNotification);
 
         // We will handle recurring donations in a separate submodule sample that will enable Subscription on the Off-site gateway sample.
         if ($this->isRecurringDonation($webhookNotification)) {
@@ -31,11 +32,44 @@ public function __invoke(OffSiteGatewayWebhookNotification $webhookNotification)
 
         switch (strtolower($webhookNotification->gatewayPaymentStatus)) {
             case 'complete':
+                $asyncJobHookName = 'givewp_' . OffSiteGateway::id() . '_event_donation_completed';
                 AsBackgroundJobs::enqueueAsyncAction(
-                    'givewp_off-site_gateway_sample_event_donation_completed',
+                    $asyncJobHookName,
                     [$webhookNotification->gatewayPaymentId],
                     'ADDON_TEXTDOMAIN'
                 );
+
+                /**
+                 * The block below is not necessary for real-world integrations;
+                 * We are adding it here just for educational purposes.
+                 */
+                $asyncJobUrl = admin_url('tools.php?page=action-scheduler&s=' . $asyncJobHookName);
+                ?>
+                <style>
+                    .container {
+                        font-family: "Open Sans", Helvetica, Arial, sans-serif;
+                        max-width: 800px;
+                        margin: 60px auto;
+                    }
+
+                    a {
+                        font-weight: bold;
+                    }
+                </style>
+                <div class="container">
+                    <h1>Webhook Notification Handler</h1>
+                    <p>
+                        ✅ We schedule an async job in the server background to change the donation status to "complete"
+                        as
+                        soon as possible. This approach prevents overloading the server as the webhook notification will
+                        be handled only when the server has enough processing power available. You can check the
+                        background job status at the following link:
+                    </p>
+                    <a href="<?php
+                    echo $asyncJobUrl ?>"> <?php
+                        echo $asyncJobUrl ?></a>
+                </div>
+                <?php
                 break;
             case 'failed':
                 // Handle failed transactions here...