DEV Community

Abdul
Abdul

Posted on

Testing Paystack Webhooks with Ngrok and Django: A Hands-On Tutorial

#webdev #django #stripe #paystack

Testing Backend API with Ngrok
Photo by Christopher Gower on Unsplash

Introduction

Ever struggled with testing payment webhooks in your local development environment? You’re not alone! One of the biggest challenges of integrating payment gateways like Paystack is testing webhooks locally. This is where Ngrok comes to the rescue!

This tutorial will guide you through setting up Ngrok to expose your local Django development server to the internet, allowing you to receive and test Paystack webhook notifications without deploying your application.

What Are Webhooks and Why Do We Need Them?

Firstly, let us learn about webhooks. Webhooks are messages sent automatically from one application to another when specific events occur. Payment processors like Paystack, or stripe rely on webhooks to notify your application about payment statuses, refunds, disputes, and more.

The challenge? Webhook notifications require a publicly accessible URL, but our Django development server typically runs locally (localhost) and cannot be accessed from the internet.

This is where Ngrok bridges the gap!

Prerequisites

Before we begin, make sure you have:

  • A Django project set up on your local machine
  • A Paystack account (Test mode is fine for this tutorial)
  • A basic understanding of how Django views and URLs work

Step 1: Install Ngrok

First, let's get Ngrok installed on your system:

  1. Visit https://ngrok.com/download
  2. Download the version appropriate for your operating system
  3. Extract the zip file to a location of your choice

macOS/Linux users: You might need to make the ngrok file executable:

chmod +x /path/to/ngrok

Windows users: After extraction, you'll have an ngrok.exe file that you can run directly.

Step 2: Create an Ngrok Account

Ngrok requires an account for authentication:

  1. Sign up at https://dashboard.ngrok.com/signup
  2. After registering, navigate to the "Auth" section in your dashboard
  3. Copy your authtoken - we'll need this in the next step

Step 3: Link Your Ngrok Account

Open your terminal or command prompt and run:

./ngrok authtoken YOUR_AUTH_TOKEN

Replace YOUR_AUTH_TOKEN with the token you copied from your dashboard.

This command sets up Ngrok to use your account, offering benefits like longer session times and more reliable connections.

Step 4: Configure Your Django Project for Webhooks

Before starting Ngrok, let's ensure our Django project is ready to receive webhooks. Add the following view to handle Paystack webhook notifications:

# In your app's views.py file
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
import json
import hmac
import hashlib
import logging

logger = logging.getLogger(__name__)

@csrf_exempt
@require_POST


def paystack_webhook(request):
    # Get Paystack signature from header
    paystack_signature = request.headers.get('x-paystack-signature')

    if not paystack_signature:
        return HttpResponse(status=400)

    # Read the request body
    payload = request.body

    # Log the payload for debugging
    logger.info(f"Received webhook: {payload.decode('utf-8')}")

    # In production, verify the signature with your Paystack secret key
    # secret_key = 'your_paystack_secret_key'
    # computed_signature = hmac.new(
    #     secret_key.encode('utf-8'),
    #     payload,
    #     hashlib.sha512
    # ).hexdigest()

    # if computed_signature != paystack_signature:
    #     return HttpResponse(status=401)

    # Process the webhook payload
    try:
        data = json.loads(payload)
        event = data.get('event')

        if event == 'charge.success':
            # Handle successful payment
            reference = data.get('data', {}).get('reference')
            amount = data.get('data', {}).get('amount')
            logger.info(f"Successful payment: {reference} for {amount}")
            # Update your database, notify customer, etc.

        elif event == 'transfer.success':
            # Handle successful transfer
            pass

        # Add other event types as needed

        return HttpResponse(status=200)
    except json.JSONDecodeError:
        logger.error("Invalid JSON payload")
        return HttpResponse(status=400)
    except Exception as e:
        logger.error(f"Error processing webhook: {str(e)}")
        return HttpResponse(status=500)
Enter fullscreen mode Exit fullscreen mode

Next, add this view to your URLs configuration:

from django.urls import path
from .views import paystack_webhook

urlpatterns = [
    # Your other URL patterns
    path('api/paystack/webhook/', paystack_webhook, name='paystack_webhook'),
]# In your app's urls.py file
Enter fullscreen mode Exit fullscreen mode

Step 5: Run Your Django Development Server

Start your Django development server:

python manage.py runserver

By default, this will run your server on 127.0.0.1:8000.

Step 6: Start Ngrok to Expose Your Server

Open a new terminal window (keep your Django server running) and start Ngrok:

./ngrok http 8000

You should see a display like this:

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.3.1
Region                        United States (us)
Latency                       24ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://a1b2c3d4.ngrok.io -> http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

The key aspect here is the forwarding URL (https://a1b2c3d4.ngrok.io in this example). This is your public URL that Paystack can utilize to send webhook notifications.

Pro Tip: You can access the Ngrok web interface at http://127.0.0.1:4040 to inspect requests in real-time - this is invaluable for debugging!

Step 7: Configure Paystack Webhook Settings

Now, let's set up Paystack to send webhook notifications to our Ngrok URL:

  1. Log in to your Paystack Dashboard
  2. Navigate to Settings > API Keys & Webhooks
  3. In the Webhook section, add your webhook URLs:
    1. Test Webhook URL: https://a1b2c3d4.ngrok.io/api/paystack/webhook/
    2. Test Callback URL: https://a1b2c3d4.ngrok.io/api/paystack/callback/ (if your app has a callback endpoint)

Make sure to replace a1b2c3d4.ngrok.io with your actual Ngrok URL.

Paystack Webhook Configuration

Step 8: Let's Test It!

There are several ways to test your webhook setup:

Option 1: Initiate a test transaction

  1. Create a test payment page in your Paystack dashboard
  2. Make a test payment using the provided test cards
  3. Watch your Ngrok terminal and Django logs for the incoming webhook

Option 2: Use Paystack's test event feature

  1. In your Paystack dashboard, go to Settings > API Keys & Webhooks
  2. Scroll down to the webhook section
  3. Click "Send Test Webhook" to trigger a test event

Common Issues and Troubleshooting

1. Webhook URL Not Receiving Events

  • Check that your Ngrok session is still active
  • Verify that the URL in your Paystack dashboard exactly matches your Ngrok URL
  • Ensure your Django server is running.

2. Django Not Processing the Webhook

  • Check your Django logs for any errors
  • Verify that your URL pattern is correct
  • Make sure CSRF protection is properly disabled for the webhook endpoint

3. Signature Verification Failing

  • Double-check your Paystack secret key
  • Ensure you're using the correct hashing algorithm (SHA512)
  • Check if the payload is being modified in transit

Beyond the Basics: Production Considerations

While this setup is perfect for testing, remember these points for production:

  1. Always verify webhook signatures in production to ensure they're genuinely from Paystack
  2. Implement proper error handling and logging for webhooks
  3. Set up retry mechanisms for failed webhook processing
  4. Don't rely on Ngrok for production – use a properly deployed application with a stable URL

Conclusion

Congratulations! You have successfully set up Ngrok to test Paystack webhooks with your Django application. This setup simplifies the development and testing of webhooks, enabling you to verify your payment integration without needing to deploy your application.

Remember, webhooks are an essential part of a robust payment integration. They ensure that your application remains in sync with payment events, even if users close their browsers or lose their internet connection.

I hope you found this tutorial helpful! If you have any experiences or questions, please feel free to share them in the comments below.

About the Author: Abduhameed is a passionate Software Engineer dedicated to simplifying development workflows and sharing knowledge with the community.

Tags: Django, Paystack, Webhooks, Ngrok, Payment Integration, Web Development, API Integration, Test Payment Gateway, Fintech Development, Django Webhooks, Secure Webhook Testing, Python, Python Web Development, Online Payments, Payment Gateway Integration, Localhost Tunneling, Developer Tools, Backend Development, Full Stack Development, SaaS Development, Software Engineering, REST API, Stripe, Flutterwave, Razorpay, Square Payments, Braintree, PayPal, Mollie, Checkout.com, Adyen, Amazon Pay, WorldPay, Africa Tech, DevOps for Webhooks, Real-time Payment Notifications

Top comments (0)