Clarification on webhook requirements for different variants

[vhsantos]

Hello again,

First of all, I truly appreciate the work put into this project. ;-)

However, I found the documentation usually a bit unclear in several topics, for example regarding webhook requirements. Specifically, on the Webhooks page, it states:

Webhooks are a crucial component in connecting your Django Payments application with external payment gateways like Stripe, PayPal, or Braintree. They enable real-time notifications or events from the payment gateway to be sent to your application, eliminating the need for continuous polling or manual API requests. With webhooks, your application can stay in sync with payment gateway updates, such as successful payments, subscription changes, or refunds.

and bellow, it mentions:

The webhook URL structure in django-payments follows this pattern:

{protocol}://{host}/payments/process/{variant}/

This could lead users to believe that ALL payment variants require a webhook setup, such as:

https://your-app.com/payments/process/stripe/
https://your-app.com/payments/process/paypal/
https://your-app.com/payments/process/mercadopago/

Nevertheless, after reviewing the static_callback code, I noticed that it calls:

 token = provider.get_token_from_request(request=request, payment=None)

And as far as I can tell, only the Stripe provider implements get_token_from_request. Other providers (I tested PayPal) raise a NotImplementedError.

If webhooks are only required for Stripe today, it might be helpful to clarify this in the documentation. Perhaps a table listing which official providers require webhooks and which do not would prevent confusion for new users.

Just a small suggestion that I believe could improve the onboarding experience.

[mariofix]

Webhooks are supported by many providers, my implementation of the stripe sdk is by creating a single PaymentIntent on Stripe for each Payment in django-payment's model, (no support for other Stripe Services or Products, for that we refer you to dj-stripe/dj-stripe
Webhooks are useful for us because it automates things AND less code for manual things like "Check Payment Status" action or the like.

Specifically for us, only Stripe's Webhook needs configuration, so, obviously, only Stripe is shown.
Other providers will be included by us in future releases or by any contributions, I personally use about 7 or 8 different providers with django payments (i develop and maintain django-payments-chile) and whatever improvement i made on my systems, I then send the relevant changes here, I updated Stripe API for that reason.

Hopefully other providers will be available in the future, but for now we rely on contributions from you as developers and users.

[WhyNotHugo]

There are two URL patterns for webhooks. Several other providers use the other pattern.

Stripe is unique in that you need to configure the URL in their portal. For (some) other providers, the webhook URL is submitted via the API request when creating a payment request.

[vhsantos]

Hello there,

I completely agree that webhooks are useful, and I’m not suggesting otherwise. My point is that the current documentation can be unclear for someone setting up Django Payments for the first time. Since only Stripe explicitly requires a configured webhook URL in the provider’s portal, but other providers handle webhooks differently (e.g., submitting the URL dynamically via API requests), the documentation could better clarify these distinctions.

Note: We know that others providers maybe are using the webhooks by default, but that is not the case of this issue.

Again, when reading the current docs, it’s easy to assume that all providers require are going to use the configured webhook at:

https://your-app.com/payments/process/{variant}/

However, this isn't the case. Since this is not clearly stated in the documentation, it can lead to confusion and unnecessary troubleshooting.

Would it be possible to update the documentation to include a table or section explaining which providers use and require webhook setup (on the provider side) and which not? That would help new users avoid mistakes and make the setup process smoother.

Suggested Improvement for the Webhooks Documentation:

==========

Webhooks in Django-Payments

Webhooks are an essential part of integrating Django-Payments with external payment gateways. They allow real-time notifications from the payment provider to update your application, eliminating the need for manual API polling or scheduled status checks.

Webhook URL Pattern

In django-payments, the webhook URL generally follows this structure:

However, not all payment providers require manual webhook setup. The table below outlines which providers need explicit webhook configuration and how they handle payment notifications:

Provider	Webhook Setup Required?	How It Works
Stripe	✅ Yes	Must be manually configured in the Stripe Dashboard
PayPal	❌ No	Payment response is processed during the transaction
Braintree	❌ No	Payment response is processed during the transaction
MercadoPago	❌ No	Payment response is processed during the transaction

Note: If your provider is not listed above, refer to its official documentation to determine if webhook setup is required.

By understanding these differences, you can ensure that your payment integration is correctly configured without unnecessary setup steps.

=====

By making this distinction clear, users will have a better understanding of when they need to configure webhooks manually versus when the provider handles it automatically.

[WhyNotHugo]

Your point is now clear to me.

I now see our previous misunderstanding; there are two things which we might call "Webhook Setup":

• Configuring URL patterns for webhooks in Django. Most providers require doing this.
• Configuring URL patterns in the provider's website. This only needs to be done for Stripe (I need to double-check MercadoPago, it might also need this step and we simply haven't documented it properly).

I like the general approach on your suggestion, but the wording "Webhook Setup Required" is ambiguous, as it can be interpreted as either of the above.