Stripe webhook verification and idempotent event handling

<p>Implementing Stripe webhooks. Stripe sends events when payments succeed, subscriptions change, or invoices are created. Need to verify webhook signatures to prevent spoofed events and handle retries idempotently.</p>

<p>Verify the Stripe signature header and use event IDs for idempotency:</p> <div class="highlight"><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">stripe</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">APIRouter</span><span class="p">,</span> <span class="n">Request</span><span class="p">,</span> <span class="n">HTTPException</span> <span class="kn">from</span><span class="w"> </span><span class="nn">app.models.payment</span><span class="w"> </span><span class="kn">import</span> <span class="n">ProcessedEvent</span> <span class="kn">from</span><span class="w"> </span><span class="nn">sqlalchemy.exc</span><span class="w"> </span><span class="kn">import</span> <span class="n">IntegrityError</span> <span class="n">router</span> <span class="o">=</span> <span class="n">APIRouter</span><span class="p">()</span> <span class="n">stripe</span><span class="o">.</span><span class="n">api_key</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">stripe_secret_key</span> <span class="nd">@router</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">'/webhooks/stripe'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">stripe_webhook</span><span class="p">(</span> <span class="n">request</span><span class="p">:</span> <span class="n">Request</span><span class="p">,</span> <span class="n">session</span><span class="p">:</span> <span class="n">AsyncSession</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_db</span><span class="p">),</span> <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">:</span> <span class="n">payload</span> <span class="o">=</span> <span class="k">await</span> <span class="n">request</span><span class="o">.</span><span class="n">body</span><span class="p">()</span> <span class="n">sig_header</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'stripe-signature'</span><span class="p">)</span> <span class="k">try</span><span class="p">:</span> <span class="n">event</span> <span class="o">=</span> <span class="n">stripe</span><span class="o">.</span><span class="n">Webhook</span><span class="o">.</span><span class="n">construct_event</span><span class="p">(</span> <span class="n">payload</span><span class="p">,</span> <span class="n">sig_header</span><span class="p">,</span> <span class="n">settings</span><span class="o">.</span><span class="n">stripe_webhook_secret</span> <span class="p">)</span> <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s1">'Invalid payload'</span><span class="p">)</span> <span class="k">except</span> <span class="n">stripe</span><span class="o">.</span><span class="n">error</span><span class="o">.</span><span class="n">SignatureVerificationError</span><span class="p">:</span> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s1">'Invalid signature'</span><span class="p">)</span> <span class="c1"># Idempotency: skip already-processed events</span> <span class="k">try</span><span class="p">:</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span> <span class="n">insert</span><span class="p">(</span><span class="n">ProcessedEvent</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">stripe_event_id</span><span class="o">=</span><span class="n">event</span><span class="p">[</span><span class="s1">'id'</span><span class="p">])</span> <span class="p">)</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span> <span class="k">except</span> <span class="n">IntegrityError</span><span class="p">:</span> <span class="c1"># Already processed — return 200 so Stripe stops retrying</span> <span class="k">return</span> <span class="p">{</span><span class="s1">'status'</span><span class="p">:</span> <span class="s1">'already_processed'</span><span class="p">}</span> <span class="c1"># Handle event types</span> <span class="k">match</span> <span class="n">event</span><span class="p">[</span><span class="s1">'type'</span><span class="p">]:</span> <span class="k">case</span> <span class="s1">'checkout.session.completed'</span><span class="p">:</span> <span class="k">await</span> <span class="n">handle_checkout_completed</span><span class="p">(</span><span class="n">event</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="s1">'object'</span><span class="p">],</span> <span class="n">session</span><span class="p">)</span> <span class="k">case</span> <span class="s1">'customer.subscription.deleted'</span><span class="p">:</span> <span class="k">await</span> <span class="n">handle_subscription_cancelled</span><span class="p">(</span><span class="n">event</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="s1">'object'</span><span class="p">],</span> <span class="n">session</span><span class="p">)</span> <span class="k">case</span> <span class="s1">'invoice.payment_failed'</span><span class="p">:</span> <span class="k">await</span> <span class="n">handle_payment_failed</span><span class="p">(</span><span class="n">event</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="s1">'object'</span><span class="p">],</span> <span class="n">session</span><span class="p">)</span> <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span> <span class="k">pass</span> <span class="c1"># Ignore unhandled event types</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="k">return</span> <span class="p">{</span><span class="s1">'status'</span><span class="p">:</span> <span class="s1">'ok'</span><span class="p">}</span> </code></pre></div> <p>Critical: Always return 200 for events you've already processed. Stripe retries on non-2xx responses. The <code>processed_events</code> table with a unique constraint on <code>stripe_event_id</code> prevents duplicate processing. Test locally with <code>stripe listen --forward-to localhost:8000/webhooks/stripe</code>.</p>