Stripe Webhooks: The Definitive Guide to Local Development without Tunnels

# Configure Stripe to send to your FetchHook URL:
# https://api.fetchhook.app/in/stash_stripe_dev

# Then pull events whenever your script is ready:
curl https://api.fetchhook.app/api/v1/stash_stripe_dev \
  -H "Authorization: Bearer fh_live_xxx"

Stripe Dashboard → Developers → Webhooks → Add endpoint

Endpoint URL:
https://api.fetchhook.app/in/stash_stripe_dev

Events to send:
✓ payment_intent.succeeded
✓ payment_intent.payment_failed
✓ customer.subscription.created
✓ customer.subscription.deleted
✓ invoice.payment_succeeded

Signing secret (save this):
whsec_xxxxx...

FetchHook will verify this signature automatically.

import requests
import os

FETCHHOOK_API_KEY = os.getenv("FETCHHOOK_API_KEY")
SOURCE_ID = "stash_stripe_dev"

def process_stripe_payments():
    # Pull all Stripe events from mailbox
    response = requests.get(
        f"https://api.fetchhook.app/api/v1/{SOURCE_ID}",
        headers={"Authorization": f"Bearer {FETCHHOOK_API_KEY}"}
    )

    if response.status_code != 200:
        print(f"Failed to fetch: {response.status_code}")
        return

    events = response.json().get('events', [])

    for event in events:
        # FetchHook already verified the signature
        if not event.get('signature_verified'):
            print(f"⚠️  Unverified event skipped: {event['id']}")
            continue

        # Safe to process - cryptographically verified
        payload = event['payload']
        event_type = payload.get('type')

        if event_type == 'payment_intent.succeeded':
            # Fulfill order
            amount = payload['data']['object']['amount']
            customer = payload['data']['object']['customer']
            print(f"✓ Payment verified: ${amount/100} from {customer}")
            fulfill_order(payload)

        elif event_type == 'payment_intent.payment_failed':
            # Handle failure
            print(f"✗ Payment failed: {payload['id']}")
            notify_customer_payment_failed(payload)

if __name__ == "__main__":
    process_stripe_payments()

// Node.js event handler pattern
const handlers = {
  'payment_intent.succeeded': async (payload) => {
    const { amount, customer } = payload.data.object;
    await fulfillOrder(customer, amount);
    await sendConfirmationEmail(customer);
  },

  'payment_intent.payment_failed': async (payload) => {
    const { customer, last_payment_error } = payload.data.object;
    await notifyPaymentFailed(customer, last_payment_error);
  },

  'customer.subscription.created': async (payload) => {
    const { customer, items } = payload.data.object;
    await provisionSubscription(customer, items);
  },

  'customer.subscription.deleted': async (payload) => {
    const { customer } = payload.data.object;
    await revokeAccess(customer);
  }
};

async function processStripeEvent(event) {
  const eventType = event.payload.type;
  const handler = handlers[eventType];

  if (handler) {
    await handler(event.payload);
  } else {
    console.log(`Unhandled event: ${eventType}`);
  }
}

# Terminal 1: Send test events with Stripe CLI
stripe trigger payment_intent.succeeded
stripe trigger customer.subscription.created
stripe trigger payment_intent.payment_failed

# Terminal 2: Pull and process in your local script
python process_stripe.py

# Output:
# ✓ Payment verified: $99.00 from cus_test123
# ✓ Subscription created: sub_test456
# ✗ Payment failed: pi_test789

# No ngrok, no server, no hassle

# Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY process_stripe.py .

# Run every minute via cron
RUN apt-get update && apt-get install -y cron
RUN echo "* * * * * python /app/process_stripe.py >> /var/log/stripe.log 2>&1" | crontab -

CMD ["cron", "-f"]

# Environment variables:
# FETCHHOOK_API_KEY=fh_prod_xxx
# STRIPE_WEBHOOK_SECRET=whsec_prod_xxx (optional, FetchHook verifies)

import logging
import sentry_sdk

# Configure logging and error tracking
logging.basicConfig(level=logging.INFO)
sentry_sdk.init(dsn="your-sentry-dsn")

def process_with_monitoring():
    try:
        events = fetch_stripe_events()
        logging.info(f"Pulled {len(events)} Stripe events")

        success = 0
        failed = 0

        for event in events:
            try:
                if not event['signature_verified']:
                    logging.warning(f"Unverified: {event['id']}")
                    continue

                process_event(event)
                success += 1

            except Exception as e:
                failed += 1
                logging.error(f"Failed: {event['id']}, {e}")
                sentry_sdk.capture_exception(e)

        # Metrics for monitoring dashboard
        logging.info(f"Processed: {success} success, {failed} failed")

        # Alert if too many failures
        if failed > success:
            send_alert("High Stripe processing failure rate")

    except Exception as e:
        logging.critical(f"Stripe processor crashed: {e}")
        sentry_sdk.capture_exception(e)