Skip to main content

Stripe Webhooks — Internal Operations Guide

This page supplements the public Stripe Webhooks documentation with internal operational details.

Architecture​

Stripe → POST /v1/webhooks/stripe → Signature Verification → Event Router → Account State Machine

Event processing pipeline​

  1. Signature verification — HMAC-SHA256 using STRIPE_WEBHOOK_SECRET from Secret Manager
  2. Idempotency check — Stripe event ID lookup in stripe_events table
  3. Event routing — dispatches to handler based on event.type
  4. Account state transition — updates account status field
  5. Notification — triggers email via notification service

Environment variables​

VariableSourceDescription
STRIPE_WEBHOOK_SECRETSecret ManagerWebhook signing secret from Stripe dashboard
STRIPE_SECRET_KEYSecret ManagerAPI key for Stripe API calls (subscription lookups)

Account state machine​

active ──[payment_failed]──→ suspended
suspended ──[payment_succeeded]──→ active
active ──[subscription.deleted]──→ suspended

Monitoring​

  • Alert: stripe_webhook_failures > 5 in 5 minutes (PagerDuty)
  • Dashboard: Stripe webhook processing latency and error rate
  • Logs: jsonPayload.component="stripe_webhook" in Cloud Logging

Testing locally​

# Forward Stripe events to local server
stripe listen --forward-to localhost:8080/v1/webhooks/stripe

# Trigger a test event
stripe trigger invoice.payment_succeeded

Retry behavior​

Stripe retries failed webhook deliveries for up to 3 days with exponential backoff. Our endpoint MUST return 200 within 20 seconds or Stripe considers it failed.

If the endpoint is down for an extended period:

  1. Check Cloud Run service health
  2. Review Cloud Logging for errors
  3. Stripe Dashboard > Developers > Webhooks shows delivery attempts
  4. After fixing, failed events replay automatically