# Examples — Tutorial House Style

# Contents

• Complete worked example: tutorial opening + one step (bad → house style)
• Checkpoint patterns
• Inline troubleshooting pattern
• Ending pattern
• Gotchas

# Complete worked example

❌ Before:

# Webhooks tutorial

In this tutorial we will learn about webhooks. Webhooks are a way for
services to notify each other. First, set up your environment and create
a project. You can use Flask, FastAPI, or Django. Then write a handler
for the webhook and test it works.

✅ After (house style):

# Receive Stripe webhooks locally

By the end you'll have a local endpoint that verifies and logs Stripe
events, reachable from the internet.

**Prerequisites:** Python 3.12, a free Stripe test account, ngrok 3.x
installed. **Time:** ~20 minutes.

## Step 1 — Create the project

    mkdir stripe-webhooks && cd stripe-webhooks
    python3 -m venv .venv
    source .venv/bin/activate
    pip install fastapi==0.115.0 uvicorn==0.30.0 stripe==10.5.0

Expected output ends with:

    Successfully installed fastapi-0.115.0 stripe-10.5.0 uvicorn-0.30.0

**Checkpoint:** `python -c "import fastapi, stripe; print('ok')"` prints `ok`.

> If you see `command not found: python3`, install Python 3.12 from
> python.org, then restart this step in a new terminal.

What changed: destination + prerequisites + time before step 1; one framework (no menu); full commands including venv activation; pinned versions; expected output; a checkpoint; the likeliest failure handled inline.

# Checkpoint patterns

✅ Observable and exact:

• "You should see {"status":"ok"}."
• "The dashboard now lists one endpoint with a green Active badge."
• "ls migrations/ shows one file ending in _init.py."

❌ Unverifiable:

• "Make sure everything is configured correctly."
• "The server should now be working."

# Inline troubleshooting pattern

Place at the step, as a quote block, most-likely first:

> **`Address already in use`** — another process holds port 8000:
> `lsof -i :8000`, stop it, rerun.
> **`401 Unauthorized` from Stripe** — you exported the live key;
> re-export the one starting with `sk_test_`.

Cap at 3 per step; more than that means the step itself needs splitting.

# Ending pattern

## What you built

A verified Stripe webhook receiver: signature checking, event logging,
and a public URL via ngrok.

## Where to go next

- Handle `invoice.paid` and update your database — see Persisting events
- Deploy the receiver — see Deploying FastAPI
- Full event catalog: Stripe docs, Webhook events

# Gotchas

• The author's environment leaks in (aliases, globally installed tools, exported variables from earlier work). Only a clean-environment replay catches these — do it, every time.
• Unpinned versions make tutorials rot silently; pin every install and date-stamp the tested versions.
• "Simply", "just", "obviously" mark exactly the places learners get stuck; delete the word, add the missing step.
• Screenshots of terminals can't be copy-pasted or diffed; use text blocks for anything the learner must compare.
• Checkpoint drift: when you edit a step, its expected output usually changes too — replay from the edited step onward, not just the step.