python 40 lines · 7 steps

Verifying signed payment webhooks in Flask

A Flask blueprint authenticates incoming payment webhooks with an HMAC signature before queuing the event for async processing.

Explained by highlit
Flask Intermediate hmac webhooks signature verification async tasks security
1import hashlib
2import hmac
3import os
4 
5from flask import Blueprint, abort, current_app, jsonify, request
6 
7from .tasks import process_payment_event
8 
9webhooks = Blueprint("webhooks", __name__)
10 
11 
12def verify_signature(payload: bytes, header: str) -> bool:
13 if not header:
14 return False
15 try:
16 timestamp, received = (part.split("=", 1)[1] for part in header.split(","))
17 except (ValueError, IndexError):
18 return False
19 
20 secret = current_app.config["WEBHOOK_SIGNING_SECRET"].encode()
21 signed = f"{timestamp}.{payload.decode()}".encode()
22 expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
23 return hmac.compare_digest(expected, received)
24 
25 
26@webhooks.route("/webhooks/payments", methods=["POST"])
27def handle_payment_webhook():
28 payload = request.get_data()
29 signature = request.headers.get("X-Signature", "")
30 
31 if not verify_signature(payload, signature):
32 current_app.logger.warning("Rejected webhook with invalid signature")
33 abort(400, description="Invalid signature")
34 
35 event = request.get_json(silent=True)
36 if event is None or "type" not in event:
37 abort(400, description="Malformed payload")
38 
39 process_payment_event.delay(event["id"], event["type"])
40 return jsonify(received=True), 202
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Always verify a webhook's signature against a shared secret before trusting its payload.
  2. 2Use constant-time comparison like hmac.compare_digest to avoid leaking secrets through timing.
  3. 3Acknowledge webhooks fast by offloading real work to a background task queue.

Related explainers

python 
import argparse
import sys
from pathlib import Path
 

Building a subcommand CLI with argparse

cli argparse subcommands
Intermediate 6 steps
python 
from collections.abc import Mapping
from typing import Any, Iterator
 
 

Flattening nested config into dotted keys

recursion generators tree-traversal
Intermediate 7 steps
python 
import csv
import io
from datetime import datetime
 

Streaming a CSV export in Flask

streaming generators csv
Intermediate 9 steps
php 
<?php
 
class ImageUploadService
{

Validating file uploads safely in PHP

file-upload input-validation security
Intermediate 8 steps
python 
import time
from collections import defaultdict
from threading import Lock
 

Sliding-window login rate limiting in Flask

rate-limiting sliding-window thread-safety
Intermediate 7 steps
php 
<?php
 
namespace App\View;
 

Building a safe HTML escaper in PHP

security xss escaping
Intermediate 6 steps

Share this explainer

Here's the card — post it anywhere.

Verifying signed payment webhooks in Flask — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code