diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 9056cd800..f2e2a3df2 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -1,7 +1,8 @@ .. _webhooks: +********* Webhooks -================= +********* Webhooks are a crucial component in connecting your Django Payments application with external payment gateways like Stripe, PayPal, or Braintree. They enable @@ -19,71 +20,16 @@ application's internal state, trigger actions, or send user notifications based on payment-related events. -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: - -* Log in to your `Stripe Dashboard `_. -* 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 `_ 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`. - URL Structure ------------- +============= The webhook URL structure in django-payments follows this pattern: + ``{protocol}://{host}/payments/process/{variant}/`` Where: -* ``{protocol}``: Configured in ``PAYMENT_PROTOCOL`` (typically "http" or "https") -* ``{host}``: Configured in ``PAYMENT_HOST`` -* ``{variant}``: The name you've configured in PAYMENT_VARIANTS +- ``{protocol}``: Configured in ``PAYMENT_PROTOCOL`` (typically "http" or "https") +- ``{host}``: Configured in ``PAYMENT_HOST`` +- ``{variant}``: The name you've configured in PAYMENT_VARIANTS For example, with this configuration: @@ -111,3 +57,65 @@ Your webhook URL would be: 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 `_. +#. 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 `_ 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`.