Requirements

• Python 3.10+

• Django 4.2+

• cryptography ~=46.0.0

1. Add to your Django URLs

# urls.py
from django.urls import path
from django_sns_signals.views import sns_webhook

urlpatterns = [
    path('sns/webhook/', sns_webhook, name='sns_webhook'),
]

2. Connect to Django Signals

# apps.py or signals.py
from django.apps import AppConfig
from django_sns_signals import sns_notification

def handle_notification(sender, notification_message, topic_arn, subject=None, **kwargs):
    """Handle SNS notifications"""
    print(f"Received from {topic_arn}: {notification_message}")
    # Your business logic here

class MyAppConfig(AppConfig):
    def ready(self):
        sns_notification.connect(handle_notification)

3. Configure SNS Topic (AWS Console)

1. Create an SNS topic in AWS

2. Add an HTTPS subscription with your webhook URL: https://yourdomain.com/sns/webhook/

3. The library will automatically confirm the subscription

Optional Settings

Add to your Django settings.py:

# Optional: Configure signing certificate cache timeout (in seconds)
# Default: 86400 (24 hours)
SNS_SIGNING_CERT_CACHE_TIMEOUT = 86400

The certificate cache timeout controls how long AWS SNS signing certificates are cached. AWS rarely rotates these certificates, so a longer cache period (24 hours or more) is safe and reduces HTTP requests.

Core Components

sns_subscription_confirmation

Fired after successful subscription confirmation.

Signal Parameters:

• message (dict) - Full parsed SNS message

• raw_message (bytes) - Raw request body

• message_id (str) - Unique message identifier

• topic_arn (str) - Topic ARN

• subject (str | None) - Optional subject

• timestamp (str) - Message timestamp

• subscribe_url (str) - Subscription confirmation URL

• token (str) - Subscription token

sns_unsubscribe_confirmation

Fired after successful unsubscribe confirmation.

Signal Parameters:

• message (dict) - Full parsed SNS message

• raw_message (bytes) - Raw request body

• message_id (str) - Unique message identifier

• topic_arn (str) - Topic ARN

• subject (str | None) - Optional subject

• timestamp (str) - Message timestamp

• subscribe_url (str) - Unsubscribe confirmation URL

• token (str) - Unsubscription token

sns_notification

Fired when a notification is received.

Signal Parameters:

• message (dict) - Full parsed SNS message

• raw_message (bytes) - Raw request body

• message_id (str) - Unique message identifier

• topic_arn (str) - Topic ARN

• subject (str | None) - Optional subject

• timestamp (str) - Message timestamp

• notification_message (str) - The actual notification payload

• unsubscribe_url (str) - URL to unsubscribe from topic

Basic Notification Handler

from django_sns_signals import sns_notification

def handle_sns_notification(sender, notification_message, topic_arn, subject=None, **kwargs):
    print(f"Topic: {topic_arn}")
    print(f"Subject: {subject}")
    print(f"Message: {notification_message}")

sns_notification.connect(handle_sns_notification)

Topic-Specific Handler

from django_sns_signals import sns_notification
import json

def handle_order_notifications(sender, notification_message, topic_arn, **kwargs):
    if 'orders' not in topic_arn:
        return  # Ignore non-order topics

    order_data = json.loads(notification_message)
    process_order(order_data)

sns_notification.connect(handle_order_notifications)

Subscription Tracking

from django_sns_signals import sns_subscription_confirmation, sns_unsubscribe_confirmation

def log_subscription(sender, topic_arn, **kwargs):
    print(f"Subscribed to: {topic_arn}")

def log_unsubscription(sender, topic_arn, **kwargs):
    print(f"Unsubscribed from: {topic_arn}")

sns_subscription_confirmation.connect(log_subscription)
sns_unsubscribe_confirmation.connect(log_unsubscription)

Message Signature Validation

All SNS messages are cryptographically validated before processing:

1. Extract SigningCertURL from SNS message

2. Validate URL hostname ends with .amazonaws.com

3. Fetch certificate (cached for performance)

4. Build canonical string-to-sign based on message type

5. Verify signature using certificate’s public key with PKCS1v15 padding and SHA1

6. Reject message if signature invalid

The library follows AWS best practices for SNS message verification as documented in the AWS SNS Developer Guide.

Setup

# Clone the repository
git clone https://github.com/newadventures/django-sns-signals.git
cd django-sns-signals

# Install in development mode
pip install -e .
pip install -r requirements_dev.txt

Running Tests

# Run tests with pytest
pytest tests/

# Or with Django's test runner
python -m django test --settings=tests.settings

# Run with coverage
pytest --cov=django_sns_signals tests/

Code Quality

# Format and lint code
ruff check src/ tests/
ruff format src/ tests/

Building the Package

# Build distribution packages
python -m build

# Check package for PyPI compliance
twine check dist/*