feature: add new methods and contract for webhook notifications

src/Framework/PaymentGateways/Contracts/WebhookNotificationsListener.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Give\Framework\PaymentGateways\Contracts;
+
+/**
+ * @since 2.20.0
+ */
+interface WebhookNotificationsListener
+{
+    /**
+     * Update subscription payment method.
+     *
+     *
+     * @unreleased
+     */
+    public function webhookNotificationsListener();
+}
+

src/Framework/PaymentGateways/PaymentGateway.php

@@ -11,10 +11,11 @@
 use Give\Framework\PaymentGateways\Contracts\Subscription\SubscriptionPausable;
 use Give\Framework\PaymentGateways\Contracts\Subscription\SubscriptionPaymentMethodEditable;
 use Give\Framework\PaymentGateways\Contracts\Subscription\SubscriptionTransactionsSynchronizable;
+use Give\Framework\PaymentGateways\Contracts\WebhookNotificationsListener;
 use Give\Framework\PaymentGateways\Routes\RouteSignature;
 use Give\Framework\PaymentGateways\Traits\HandleHttpResponses;
 use Give\Framework\PaymentGateways\Traits\HasRouteMethods;
-use Give\Framework\PaymentGateways\Webhooks\WebhookEvents;
+use Give\Framework\PaymentGateways\Webhooks\Webhook;
 use Give\Framework\Support\ValueObjects\Money;
 use Give\Log\Log;
 use Give\Subscriptions\Models\Subscription;
@@ -46,9 +47,9 @@ abstract class PaymentGateway implements PaymentGatewayInterface,
     /**
      * @unreleased
      *
-     * @var WebhookEvents $webhookEvents
+     * @var Webhook $webhook
      */
-    public $webhookEvents;
+    public $webhook;
 
     /**
      * @unreleased Add the webhookEvents property
@@ -65,17 +66,25 @@ public function __construct(SubscriptionModule $subscriptionModule = null)
         }
 
         $this->subscriptionModule = $subscriptionModule;
-        $this->webhookEvents = new WebhookEvents($this::id());
+        $this->webhook = new Webhook($this);
     }
 
     /**
      * @unreleased
      */
-    public static function webhookEvents(): WebhookEvents
+    public static function webhook(): Webhook
     {
         $instance = new static();
 
-        return $instance->webhookEvents;
+        return $instance->webhook;
+    }
+
+    /**
+     * @unreleased
+     */
+    public function canListeningWebhookNotifications(): bool
+    {
+        return $this instanceof WebhookNotificationsListener;
     }
 
     /**

src/Framework/PaymentGateways/Webhooks/Webhook.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Give\Framework\PaymentGateways\Webhooks;
+
+use Give\Framework\Exceptions\Primitives\Exception;
+use Give\Framework\PaymentGateways\PaymentGateway;
+
+/**
+ * @unreleased
+ */
+class Webhook
+{
+    /**
+     * @unreleased
+     *
+     * @var string $webhookNotificationsListener
+     */
+    private $webhookNotificationsListener = 'webhookNotificationsListener';
+
+    /**
+     * @unreleased
+     *
+     * @var PaymentGateway $paymentGateway
+     */
+    private $paymentGateway;
+
+    /**
+     * @unreleased
+     *
+     * @var WebhookEvents $webhookEvents
+     */
+    public $events;
+
+    public function __construct(PaymentGateway &$paymentGateway)
+    {
+        $paymentGateway->routeMethods[] = $this->webhookNotificationsListener;
+        $this->paymentGateway = &$paymentGateway;
+        $this->events = new WebhookEvents($paymentGateway::id());
+    }
+
+    /**
+     * @unreleased
+     *
+     * @throws Exception
+     */
+    public function getNotificationUrl(): string
+    {
+        if ( ! $this->paymentGateway->canListeningWebhookNotifications()) {
+            throw new Exception('Gateway does not support listening webhook notifications.');
+        }
+
+        return $this->paymentGateway->generateGatewayRouteUrl($this->webhookNotificationsListener);
+    }
+}