Skip to main content

A library to aid Django integration with Stripe.

Project description


Provides a light-touch Django integration with Stripe.

We handle Stripe webhook security & persisting all events, while allowing your project to take care of the business logic.

Requires Python 3.8+ & Django 3.2+.

Installation & Usage

pip install django-stripe-lite

Include the app in your INSTALLED_APPS setting:


Include the URLs in your URL conf:

from django.urls import include, path

urlpatterns = [
    # Assuming we're at the root, this will make the webhook
    # available at /stripe/webhook/
    path("stripe/", include("django_stripe.urls", namespace="stripe"))

Set the required settings in your settings file:

STRIPE_WEBHOOK_SECRET = "whsec_0DoBceBjS0jjm7aQj459FXiFSluJEBxt"

Run the migrations:

python migrate django_stripe

Set up your event handlers:

Event handlers are simply functions in your code base, which are wrapped with a decorator which signifies that they wish to handle a particular event type (or multiple) when it is received via the webhook.

All event handlers must be imported at application startup, otherwise the decorator wil not be able to register them against the event type. An easy way to ensure this in your local project is to trigger the import in one of your Django Apps method (see the docs).

When a webhook event is received, all processing of it is wrapped in a transaction such that a single event handler failure will result in an HTTP 500 returned from the endpoint and the transaction will be rolled back resulting in no database changes for that request. This means that the WebhookEvent is not persisted unless:

  • it was received successfully and there were no active handlers registered for the event type, or:
  • it was received successfully and processed successfully by all active handlers registered against the event type.
from django_stripe.models import WebhookEvent
from django_stripe.webhooks import stripe_webhook_handler

# Single event handler
def delete_customer_subscription(event: WebhookEvent) -> Any:
    # (dict, Stripe Event field, the object which triggered the webhook event)
    # event.event_type (str, the full event type name e.g customer.subscription.deleted)
    # event.mode (textchoices, LIVE or TEST)
    # event.stripe_created_at (datetime, when Stripe created the event)
    # event.db_created_at (datetime, when the database initially saved the event)
    # event.db_last_updated_at (datetime, when the database last saved the event)
    # event.stripe_id (str, Stripe Event ID)
    # event.api_version (str, Stripe API version)
    # event.request_id (str, the Stripe ID of the instigating request, if available)
    # event.request_idempotency_key (str, the idempotency key of the instigating request, if available)
    # event.is_processed (bool, whether the event was processed by a handler successfully)
    # event.headers (dict, the headers of the webhook request)
    # event.remote_ip (str, Remote IP of the webhook request)

# Multiple event handler
def customer_handler(event: WebhookEvent) -> Any:
    # See notes above for event structure.

That's it, you should be able to start receiving webhook events with the Stripe CLI test client. Then once you're ready, setup the production webhook via the Stripe dashboard.


Check out the repo, then get the deps:

poetry install


Running tests

The tests themselves use pytest as the test runner. If you have installed the poetry evironment, you can run them:

$ poetry run pytest

The CI suite is controlled by tox, which contains a set of environments that will format (fmt), lint, and test against all supported Python + Django version combinations.

$ tox


CI is handled by GitHub Actions. See the Actions tab on Github & the .github/workflows folder.

Publish to PyPi

Update versions, then:

poetry build
poetry publish

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_stripe_lite-0.6.0.tar.gz (10.1 kB view hashes)

Uploaded Source

Built Distribution

django_stripe_lite-0.6.0-py3-none-any.whl (12.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page