Issue #425 (#426)

* Issue #425
* Update backends.rst
* Improved webhooks.rst

docs/backends.rst

@@ -312,12 +312,9 @@ These are the community providers compatible with ``django-payments``
   * - `RazorPay <https://razorpay.com/>`_
     - IN
     - `NyanKiyoshi/django-payments-razorpay <https://github.com/NyanKiyoshi/django-payments-razorpay>`_
-  * - `Flow Chile <https://flow.cl>`_
+  * - Common providers from Chile
     - CL
-    - `mariofix/django-payments-flow <https://github.com/mariofix/django-payments-flow>`_
-  * - `Khipu <https://khipu.com>`_
-    - CL
-    - `mariofix/django-payments-khipu <https://github.com/mariofix/django-payments-khipu>`_
+    - `mariofix/django-payments-chile <https://github.com/mariofix/django-payments-chile>`_
 
 
 Creating a New Provider Backend

docs/webhooks.rst

@@ -1,8 +1,7 @@
 .. _webhooks:
 
 Webhooks
-=================
-
+*********
 
 Webhooks are a crucial component in connecting your Django Payments application
 with external payment gateways like Stripe, PayPal, or Braintree. They enable
@@ -20,49 +19,25 @@ application's internal state, trigger actions, or send user notifications based
 on payment-related events.
 
 
-Stripe
--------
+URL Structure
+=============
+The webhook URL structure in django-payments follows this pattern:
 
-Setting up Webhooks in Stripe
-To receive payment notifications and updates from Stripe, you need to set up
-webhooks. Follow these steps to configure webhooks in your Stripe Dashboard:
+``{protocol}://{host}/payments/process/{variant}/``
 
-* Log in to your `Stripe Dashboard <https://dashboard.stripe.com/>`_.
-* In the left sidebar, click on **Developers** and then select **Webhooks**.
-* Click on the "+ Add endpoint" button to create a new webhook listener.
-* In the "Endpoint URL" field, enter the URL for the Stripe variant in your
-  Django Payments application. This URL should be the endpoint where Stripe
-  will send the webhook events. Make sure the URL is accessible from the
-  internet. Example: ``https://your-app.com/payments/stripe/``.
-* From the "Events to send" dropdown, choose the specific events you want to
-  receive notifications for. You need (at least) these events:
-  * checkout.session.async_payment_failed
-  * checkout.session.async_payment_succeeded
-  * checkout.session.completed
-  * checkout.session.expired
-* Click on the "Add endpoint" button to save your webhook listener.
-* Once the webhook is created, you will see its details in the "Webhooks"
-  section. Take note of the "Signing secret" provided by Stripe as you will
-  need it later when configuring the webhook handler in your Django application
-* Test the webhook by sending a test event to your endpoint. Stripe provides a
-  "Send test webhook" button on the webhook details page. Use this feature to
-  ensure your endpoint is correctly configured and can receive and process
-  events from Stripe.
+Where:
 
-.. note::
+- ``{protocol}``: Configured in ``PAYMENT_PROTOCOL`` (typically "http" or "https")
+- ``{host}``: Configured in ``PAYMENT_HOST``
+- ``{variant}``: The name you've configured in PAYMENT_VARIANTS
 
-  It's essential to secure your webhook endpoint and verify the authenticity of
-  the events sent by Stripe. It's it not recomended to use `secure_endpoint`
-  set to false in production.
 
-Make sure to replace **https://your-app.com/payments/stripe/** with the actual
-URL for your Stripe webhook endpoint. In this case, ``stripe`` is the `variant`
-of the configured provider. E.g.:
+For example, with this configuration:
 
 .. code-block:: python
 
   PAYMENT_VARIANTS = {
-      'stripe': (  # <-- This value
+      'stripe': (  # <-- This is your variant name
           'payments.stripe.StripeProviderV3',
           {
               'api_key': 'sk_test_123456',
@@ -72,3 +47,78 @@ of the configured provider. E.g.:
           }
       )
   }
+
+  PAYMENT_HOST = 'your-app.com'
+  PAYMENT_PROTOCOL = 'https'
+
+Your webhook URL would be:
+``https://your-app.com/payments/process/stripe/``
+
+.. note::
+
+  Make sure the URL matches exactly, including the trailing slash. A common source
+  of 404 errors is using the wrong URL pattern or forgetting the trailing slash.
+
+
+Stripe
+======
+
+Setting up Webhooks in Stripe
+To receive payment notifications and updates from Stripe, you need to set up
+webhooks. Follow these steps to configure webhooks in your Stripe Dashboard:
+
+1. Log in to your `Stripe Dashboard <https://dashboard.stripe.com/>`_.
+#. In the left sidebar, click on **Developers** and then select **Webhooks**.
+#. Click on the "+ Add endpoint" button to create a new webhook listener.
+#. In the "Endpoint URL" field, enter the URL for the Stripe variant in your
+   Django Payments application. This URL should follow the pattern:
+   ``https://your-app.com/payments/process/{variant}/``, where ``{variant}`` is
+   the name you've configured in your PAYMENT_VARIANTS setting.
+   For example: ``https://your-app.com/payments/process/stripe/``
+#. From the "Events to send" dropdown, choose the specific events you want to
+   receive notifications for. You need (at least) these events:
+
+   - checkout.session.async_payment_failed
+   - checkout.session.async_payment_succeeded
+   - checkout.session.completed
+   - checkout.session.expired
+
+#. Click on the "Add endpoint" button to save your webhook listener.
+#. Once the webhook is created, you will see its details in the "Webhooks"
+   section. Take note of the "Signing secret" provided by Stripe as you will
+   need it later when configuring the webhook handler in your Django application
+#. Test the webhook by sending a test event to your endpoint. Stripe provides a
+   "Send test webhook" button on the webhook details page. Use this feature to
+   ensure your endpoint is correctly configured and can receive and process
+   events from Stripe.
+
+
+Testing with Stripe CLI
+----------------------
+
+The `Stripe CLI <https://stripe.com/docs/stripe-cli#install>`_ provides a simple
+way to test webhooks during local development by forwarding Stripe events to
+your local server. After installing and running ``stripe login``, you can start
+forwarding events to your local Django server with
+``stripe listen --forward-to localhost:8000/payments/process/stripe/``
+Use the webhook signing secret provided by the CLI in your development settings.
+
+.. code-block:: bash
+
+   # Start webhook forwarding
+   stripe listen --forward-to localhost:8000/payments/process/stripe/
+
+   # In another terminal, trigger test events
+   stripe trigger checkout.session.completed
+
+
+.. note::
+
+  It's essential to secure your webhook endpoint and verify the authenticity of
+  the events sent by Stripe. It's not recommended to use `secure_endpoint`
+  set to false in production.
+
+.. warning::
+
+  Remember to setup ``PAYMENT_HOST`` and ``PAYMENT_PROTOCOL`` in your settings file,
+  otherwise the webhooks won't work, as defined in :ref:`settings`.