5 Stripe webhook patterns that saved our SaaS at 2am

As a developer working on BillingWatch (a SaaS platform built using FastAPI and integrated with Stripe), I've encountered numerous situations where timely intervention has prevented potential disasters. In this article, we'll dive into five real-world examples of how Stripe webhooks have helped us save the day.

Example 1: Duplicate Event Idempotency

One evening, our team noticed an unusual spike in duplicate payment events from Stripe. After investigating, we realized that a temporary issue with our API had caused repeated notifications for the same transactions. To mitigate this, we implemented idempotent handling of webhooks using a simple yet effective technique:

from fastapi import FastAPI

app = FastAPI()

@app.post("/stripe/webhook/")
async def handle_stripe_webhook(webhook: Webhook):
    # Check if event is a duplicate (e.g., by comparing payload hashes)
    if is_duplicate_event(webhook.payload):
        return {"message": "Duplicate event ignored"}

    # Process the webhook as usual
    process_webhook(webhook)

By detecting and discarding duplicate events, we significantly reduced the likelihood of unnecessary processing and errors.

Example 2: Failed Payment Retry Storms

Another time, our platform encountered a surge in failed payment retries due to a temporary issue with Stripe's API. To prevent this from overwhelming our system:

import logging

logger = logging.getLogger(__name__)

def process_webhook(webhook):
    if webhook.event.type == "payment_failed":
        # Exponential backoff for retrying failed payments (e.g., 2^3, 2^4, etc.)
        retry_delay = 2 ** (webhook.timestamp - webhook.attempt_count)
        await async_sleep(retry_delay)

By introducing a carefully crafted exponential backoff mechanism, we were able to absorb the retry storm and maintain our platform's stability.

Example 3: Subscription Churn Spikes at Billing Cycle

During one billing cycle, our team noticed an unusual increase in subscription churn events. Further investigation revealed that this spike was due to an underlying issue with our pricing model. To better identify such anomalies:

from fastapi import FastAPI

app = FastAPI()

@app.post("/stripe/webhook/")
async def handle_stripe_webhook(webhook: Webhook):
    # Monitor subscription churn events (e.g., by tracking changes in user status)
    if is_subscription_churn(webhook.payload):
        # Trigger alerts and analytics to investigate the anomaly
        send_alerts_and_analyze(webhook)

By monitoring subscription churn events and triggering alerts when anomalies are detected, we were able to proactively address the underlying issue before it affected our customers.

Example 4: Webhook Signature Validation Failures

One morning, our team encountered an unexpected surge in webhook signature validation failures. After investigating, we determined that this was due to a temporary issue with our API's secret key configuration:

from fastapi import FastAPI

app = FastAPI()

@app.post("/stripe/webhook/")
async def handle_stripe_webhook(webhook: Webhook):
    # Verify webhook signatures using Stripe's public key (e.g., via HMAC-SHA256)
    if not verify_webhook_signature(webhook.signature):
        return {"message": "Invalid webhook signature"}

    # Process the webhook as usual
    process_webhook(webhook)

By verifying webhook signatures with a secure approach, we ensured that only trusted notifications reached our platform.

Example 5: Anomaly Detection

Finally, during an overnight monitoring session, our team detected an unusual anomaly in Stripe's payment events. This anomaly was caused by a previously unknown billing bug that had gone undetected until it began affecting customers:

from fastapi import FastAPI

app = FastAPI()

@app.post("/stripe/webhook/")
async def handle_stripe_webhook(webhook: Webhook):
    # Monitor anomalies in payment events (e.g., via statistical analysis)
    if is_anomaly_in_payment_event(webhook.payload):
        # Trigger alerts and analytics to investigate the anomaly
        send_alerts_and_analyze(webhook)

By employing an effective anomaly detection mechanism, we were able to identify and address this issue before our customers noticed it.

Conclusion

These five examples demonstrate how Stripe webhooks can be leveraged to prevent potential disasters at our SaaS platform. By monitoring for duplicate events, failed payment retries, subscription churn spikes, webhook signature validation failures, and anomalies in payment events, we've safeguarded our system against unexpected issues.

If you're working with FastAPI and Stripe, I encourage you to explore these webhooks patterns and adapt them to your own use cases. This will enable you to build a more robust and reliable platform that can withstand the pressures of real-world usage.

---

Related Articles

• How BillingWatch handles Stripe webhooks for real-time subscription updates
• Implementing anomaly detection in FastAPI with Stripe webhooks