Webhook handling with signature verification and idempotency

<p>I need to handle webhooks from multiple providers (Stripe, GitHub, custom services). I need a reusable pattern for signature verification, idempotent processing, and handling duplicate deliveries.</p>

<p>Generic webhook handler with verification:</p> <div class="highlight"><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">hashlib</span> <span class="kn">import</span><span class="w"> </span><span class="nn">hmac</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="n">router</span> <span class="o">=</span> <span class="n">APIRouter</span><span class="p">()</span> <span class="k">def</span><span class="w"> </span><span class="nf">verify_hmac_signature</span><span class="p">(</span> <span class="n">payload</span><span class="p">:</span> <span class="nb">bytes</span><span class="p">,</span> <span class="n">signature</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">secret</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">algorithm</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'sha256'</span><span class="p">,</span> <span class="n">prefix</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'sha256='</span><span class="p">,</span> <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span> <span class="w"> </span><span class="sd">"""Verify HMAC signature (GitHub/Stripe style)."""</span> <span class="n">expected</span> <span class="o">=</span> <span class="n">hmac</span><span class="o">.</span><span class="n">new</span><span class="p">(</span> <span class="n">secret</span><span class="o">.</span><span class="n">encode</span><span class="p">(),</span> <span class="n">payload</span><span class="p">,</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">hashlib</span><span class="p">,</span> <span class="n">algorithm</span><span class="p">),</span> <span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span> <span class="n">provided</span> <span class="o">=</span> <span class="n">signature</span><span class="o">.</span><span class="n">removeprefix</span><span class="p">(</span><span class="n">prefix</span><span class="p">)</span> <span class="k">return</span> <span class="n">hmac</span><span class="o">.</span><span class="n">compare_digest</span><span class="p">(</span><span class="n">expected</span><span class="p">,</span> <span class="n">provided</span><span class="p">)</span> <span class="c1"># Timing-safe comparison</span> <span class="nd">@router</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">'/webhooks/github'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">github_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">db</span><span class="p">:</span> <span class="n">DbSession</span><span class="p">,</span> <span class="n">x_hub_signature_256</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Header</span><span class="p">(</span><span class="kc">None</span><span class="p">),</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="k">if</span> <span class="ow">not</span> <span class="n">verify_hmac_signature</span><span class="p">(</span> <span class="n">payload</span><span class="p">,</span> <span class="n">x_hub_signature_256</span> <span class="ow">or</span> <span class="s1">''</span><span class="p">,</span> <span class="n">settings</span><span class="o">.</span><span class="n">github_webhook_secret</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'sha256='</span><span class="p">,</span> <span class="p">):</span> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="mi">401</span><span class="p">,</span> <span class="s1">'Invalid signature'</span><span class="p">)</span> <span class="n">event</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">'X-GitHub-Event'</span><span class="p">)</span> <span class="n">delivery_id</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">'X-GitHub-Delivery'</span><span class="p">)</span> <span class="c1"># Idempotency:</span> <span class="k">if</span> <span class="k">await</span> <span class="n">is_processed</span><span class="p">(</span><span class="n">db</span><span class="p">,</span> <span class="n">delivery_id</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">'duplicate'</span><span class="p">}</span> <span class="n">body</span> <span class="o">=</span> <span class="k">await</span> <span class="n">request</span><span class="o">.</span><span class="n">json</span><span class="p">()</span> <span class="k">match</span> <span class="n">event</span><span class="p">:</span> <span class="k">case</span> <span class="s1">'push'</span><span class="p">:</span> <span class="k">await</span> <span class="n">handle_push</span><span class="p">(</span><span class="n">body</span><span class="p">)</span> <span class="k">case</span> <span class="s1">'pull_request'</span><span class="p">:</span> <span class="k">await</span> <span class="n">handle_pr</span><span class="p">(</span><span class="n">body</span><span class="p">)</span> <span class="k">await</span> <span class="n">mark_processed</span><span class="p">(</span><span class="n">db</span><span class="p">,</span> <span class="n">delivery_id</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>Key points: - hmac.compare_digest prevents timing attacks (constant-time comparison) - Read raw bytes BEFORE parsing JSON -- signature is over raw bytes - Store delivery_id for idempotency -- webhooks are delivered at-least-once - Return 200 for unknown event types -- provider retries on non-2xx - Read body() once and cache -- Request.body() can only be read once in some frameworks</p>