Handling Stripe Webhooks
Set up and process Stripe webhooks to react to asynchronous payment events like successful payments, failures, and cancellations.
Handling Stripe Webhooks is a free AI Powered SaaS: Stripe + Auth + Billing + Deploy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Powered SaaS: Stripe + Auth + Billing + Deploy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What are Webhooks?
Imagine you're waiting for a package. You could constantly call the delivery company (polling) to ask for updates, or they could simply call you (webhook) when the package arrives. Webhooks are automated messages sent by one system to another when a specific event occurs.
They act like a notification system, allowing applications to communicate in real-time about changes or events.
Why Stripe Webhooks?
Payment processing is often asynchronous. This means an action, like a payment, might not complete instantly. It could take time, or even fail, after your user initiates it.
Stripe uses webhooks to notify your application about these crucial asynchronous events. Instead of constantly asking Stripe for updates, Stripe tells your app when a payment succeeds, a subscription renews, a refund is issued, or a failure occurs.
Key Stripe Event Types
Stripe sends different types of webhook events depending on what happened. Each event type has a unique identifier.
checkout.session.completed: A customer finished a Stripe Checkout session.invoice.payment_succeeded: A payment for an invoice (often related to subscriptions) was successful.customer.subscription.updated: A subscription changed status (e.g., from active to canceled).payment_intent.succeeded: A payment intent successfully captured funds.
These are just a few; there are many more to cover various scenarios.
Your Webhook Endpoint
To receive Stripe webhooks, your application needs a publicly accessible HTTP endpoint (a URL) that can accept POST requests. This endpoint will be the listener for all incoming Stripe events.
Here's a basic Python Flask example of what such an endpoint might look like:
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/stripe-webhook', methods=['POST'])
def stripe_webhook():
# Stripe will send event data here
payload = request.get_data(as_text=True)
print(f"Received webhook: {payload[:100]}...") # Log first 100 chars
return jsonify(success=True), 200 # Always respond with 200 OK
if __name__ == '__main__':
# Run on a port for local testing. In production, use a server like Gunicorn.
app.run(port=4242, debug=True)Register with Stripe
Once you have your endpoint, you need to tell Stripe where to send the events. You do this in the Stripe Dashboard.
- Go to Developers > Webhooks.
- Click Add endpoint.
- Enter your public URL (e.g.,
https://yourdomain.com/stripe-webhook). - Select the event types you want to receive.
For local development, you can use the Stripe CLI's stripe listen command to forward events to your local endpoint.
Receiving Event Data
When an event occurs, Stripe sends a JSON payload to your endpoint. This payload contains all the details about the event, including its id, type, and the data object related to the event (e.g., a checkout.session or invoice object).
Your endpoint will read this JSON and decide what to do next based on the type of event.
from flask import Flask, request, jsonify
import json
app = Flask(__name__)
@app.route('/stripe-webhook', methods=['POST'])
def stripe_webhook():
event = json.loads(request.get_data())
event_id = event['id']
event_type = event['type']
print(f"Processing event ID: {event_id}, Type: {event_type}")
# In a real application, you'd perform actions here
# based on the event_type.
return jsonify(success=True), 200
if __name__ == '__main__':
app.run(port=4242, debug=True)Verify Webhook Signatures
This is crucial for security! Anyone could send a fake POST request to your webhook URL. To ensure an event genuinely came from Stripe and hasn't been tampered with, you must verify its signature.
Stripe includes a unique signature in the Stripe-Signature header of each webhook request. You'll use your webhook secret (from the Stripe Dashboard) to verify it.
from flask import Flask, request, jsonify
import stripe
import os
app = Flask(__name__)
# IMPORTANT: Use environment variables for secrets!
# For this example, replace with your actual keys:
stripe.api_key = "sk_test_YOUR_STRIPE_SECRET_KEY"
webhook_secret = "whsec_YOUR_WEBHOOK_SECRET" # Get from Stripe Dashboard
@app.route('/stripe-webhook', methods=['POST'])
def stripe_webhook():
payload = request.get_data()
sig_header = request.headers.get('stripe-signature')
event = None
try:
event = stripe.Webhook.construct_event(
payload, sig_header, webhook_secret
)
except ValueError as e:
# Invalid payload
print(f"Error: Invalid payload - {e}")
return "Invalid payload", 400
except stripe.error.SignatureVerificationError as e:
# Invalid signature
print(f"Error: Invalid signature - {e}")
return "Invalid signature", 400
# If we reach here, the event is verified and safe to process
print(f"Verified event type: {event['type']}")
return jsonify(success=True), 200
if __name__ == '__main__':
app.run(port=4242, debug=True)Processing Specific Events
Once an event is verified, your application can then process it based on its type. This typically involves updating your database, sending emails, or triggering other business logic.
It's common to use a switch statement or if/elif chain to handle different event types.
from flask import Flask, request, jsonify
import stripe
import os
app = Flask(__name__)
stripe.api_key = "sk_test_YOUR_STRIPE_SECRET_KEY"
webhook_secret = "whsec_YOUR_WEBHOOK_SECRET"
@app.route('/stripe-webhook', methods=['POST'])
def stripe_webhook():
payload = request.get_data()
sig_header = request.headers.get('stripe-signature')
event = None
try:
event = stripe.Webhook.construct_event(payload, sig_header, webhook_secret)
except Exception as e:
return str(e), 400
# Handle the event based on its type
if event['type'] == 'checkout.session.completed':
session = event['data']['object']
print(f"Checkout Session Completed: {session['id']}")
# TODO: Fulfill purchase, grant user access
elif event['type'] == 'invoice.payment_succeeded':
invoice = event['data']['object']
print(f"Invoice Payment Succeeded: {invoice['id']}")
# TODO: Update user's subscription status, send receipt
elif event['type'] == 'customer.subscription.deleted':
subscription = event['data']['object']
print(f"Subscription Deleted: {subscription['id']}")
# TODO: Revoke user access
else:
print(f"Unhandled event type: {event['type']}")
return jsonify(success=True), 200
if __name__ == '__main__':
app.run(port=4242, debug=True)Webhook Best Practices
- Respond Quickly: Stripe expects a
200 OKresponse within a few seconds. If processing is heavy, do it asynchronously (e.g., send to a queue). - Idempotency: Design your event handlers to be idempotent. Stripe might send the same event multiple times, so ensure processing an event twice doesn't cause issues.
- Error Handling: Implement robust logging and error handling. If your endpoint returns an error, Stripe will retry sending the event.
- Security: Always use HTTPS for your webhook endpoint.
Webhook Security Check
When setting up a Stripe webhook endpoint, which of the following is the most critical security measure to implement?
Recap: Handling Webhooks
In this lesson, we explored how to handle Stripe webhooks. You learned that webhooks are essential for reacting to asynchronous payment events in real-time.
- You create a dedicated endpoint in your application.
- You register this endpoint in the Stripe Dashboard.
- Crucially, you verify the webhook signature to ensure authenticity and integrity.
- Finally, you process different event types to keep your application's state synchronized with Stripe's, fulfilling orders, updating subscriptions, and more.
Frequently asked questions
Is the “Handling Stripe Webhooks” lesson free?
Yes — the full text of “Handling Stripe Webhooks” is free to read here on the web, and the AI Powered SaaS: Stripe + Auth + Billing + Deploy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Powered SaaS: Stripe + Auth + Billing + Deploy course, upgrade to CoddyKit PRO.
What will I learn in “Handling Stripe Webhooks”?
Set up and process Stripe webhooks to react to asynchronous payment events like successful payments, failures, and cancellations. You practise AI Powered SaaS: Stripe + Auth + Billing + Deploy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start AI Powered SaaS: Stripe + Auth + Billing + Deploy?
No prior experience is required. AI Powered SaaS: Stripe + Auth + Billing + Deploy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Handling Stripe Webhooks” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this AI Powered SaaS: Stripe + Auth + Billing + Deploy lesson?
Yes. Every AI Powered SaaS: Stripe + Auth + Billing + Deploy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Subscription Management
- Handling Stripe Webhooks
- Customer Portal & Billing History
- Metered Billing & Usage-Based Pricing