Python webhooks: Flask and FastAPI handlers that verify signatures

Receive webhooks in Python with Flask or FastAPI: verify the HMAC signature over the raw body, skip duplicate deliveries and answer before slow work. One verification module, tested with nothing but the standard library, serves both frameworks; one test script checks the finished server.
Get a free webhook URL Free, no account needed.

By the HookWatcher team · Updated

What you'll build

The endpoint receives GitHub webhooks, but the pattern is the same for any provider that signs with HMAC-SHA256. In order, the Flask or FastAPI handler:

  1. verifies X-Hub-Signature-256 over the raw body bytes, before anything parses them, and answers 401 if it doesn't match;
  2. requires an X-GitHub-Delivery ID and parses the JSON (400 if either is missing or broken);
  3. skips a delivery ID it has already processed with a 200, so GitHub records success and the event runs once;
  4. answers 202 straight away and does the work after the response, because GitHub gives up after 10 seconds.
What the finished handler returns
RequestStatusBody
Valid signature, new delivery202accepted
Same delivery ID again200duplicate
Missing or wrong signature, or body changed after signing401invalid signature
Valid signature, no delivery ID or not JSON400missing delivery id / invalid JSON

You need Python 3.10 or later (the code uses str | None type hints). Pick one framework; the verification module and the tests are the same for both.

Set up the project

Terminal
mkdir github-webhooks && cd github-webhooks
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install flask                # or: pip install "fastapi[standard]"

Verify the signature

hmac.compare_digest compares in constant time, so the response time doesn't reveal how much of a forged signature was right. The secret is bytes: hmac.new rejects a str key with a TypeError.

verify.py
import hashlib
import hmac


def verify_github(payload: bytes, header: str | None, secret: bytes) -> bool:
    """True when header is "sha256=" + the hex HMAC-SHA256 of the raw body."""
    if not header or not header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(secret, payload, hashlib.sha256).hexdigest()
    # Compare bytes: compare_digest raises TypeError on non-ASCII str, and the header is untrusted.
    return hmac.compare_digest(expected.encode(), header.encode())

Test it with GitHub's published test values, using only the standard library:

test_verify.py
import unittest

from verify import verify_github

# GitHub's published test values (docs: Validating webhook deliveries).
SECRET = b"It's a Secret to Everybody"
BODY = b"Hello, World!"
SIGNATURE = "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17"


class VerifyGitHubTest(unittest.TestCase):
    def test_accepts_githubs_test_signature(self):
        self.assertTrue(verify_github(BODY, SIGNATURE, SECRET))

    def test_rejects_changes(self):
        self.assertFalse(verify_github(b"Hello, World?", SIGNATURE, SECRET))
        self.assertFalse(verify_github(BODY, SIGNATURE, b"another secret"))
        self.assertFalse(verify_github(BODY, SIGNATURE[:-1], SECRET))
        self.assertFalse(verify_github(BODY, None, SECRET))
        self.assertFalse(verify_github(BODY, "sha256=" + "é" * 64, SECRET))  # no exception


if __name__ == "__main__":
    unittest.main()
Terminal
python -m unittest -v   # Ran 2 tests ... OK

Flask handler

request.get_data() returns the body as bytes, and caches it. Call it before touching request.form: once form data has been parsed, Flask's docs warn that get_data() returns nothing. Delivery IDs are guarded with a lock because Flask's development server handles requests in threads.

app.py
import json
import os
import threading

from flask import Flask, request

from verify import verify_github

SECRET = os.environ["GITHUB_WEBHOOK_SECRET"].encode()  # KeyError at startup if unset

app = Flask(__name__)
app.config["MAX_CONTENT_LENGTH"] = 25 * 1024 * 1024  # GitHub's payload cap
seen: set[str] = set()  # processed delivery IDs; use a unique database key in production
seen_lock = threading.Lock()  # the development server handles requests in threads


def text(body: str, status: int):
    return body, status, {"Content-Type": "text/plain"}


@app.post("/webhooks/github")
def github_webhook():
    body = request.get_data()  # raw bytes, read before request.form or get_json()
    if not verify_github(body, request.headers.get("X-Hub-Signature-256"), SECRET):
        return text("invalid signature", 401)

    delivery = request.headers.get("X-GitHub-Delivery")
    if not delivery:
        return text("missing delivery id", 400)

    try:
        payload = json.loads(body)
    except ValueError:  # includes invalid UTF-8
        return text("invalid JSON", 400)

    with seen_lock:
        if delivery in seen:
            return text("duplicate", 200)
        seen.add(delivery)

    event = request.headers.get("X-GitHub-Event", "")
    threading.Thread(target=handle_event, args=(event, payload)).start()  # use a task queue in production
    return text("accepted", 202)


def handle_event(event: str, payload: dict) -> None:
    print(event, payload.get("action", ""), payload.get("repository", {}).get("full_name", ""))

FastAPI handler

Take the Starlette Request directly and await request.body(). Don't declare a Pydantic model parameter for this route: FastAPI would parse and validate the body before your signature check runs. Validate after verifying, for example with Event.model_validate_json(body). BackgroundTasks run after the response is sent.

main.py
import json
import os

from fastapi import BackgroundTasks, FastAPI, Request, Response

from verify import verify_github

SECRET = os.environ["GITHUB_WEBHOOK_SECRET"].encode()  # KeyError at startup if unset

app = FastAPI()
seen: set[str] = set()  # one event loop per worker: no lock needed; use a database in production


def text(body: str, status: int) -> Response:
    return Response(content=body, status_code=status, media_type="text/plain")


@app.post("/webhooks/github")
async def github_webhook(request: Request, background: BackgroundTasks) -> Response:
    body = await request.body()  # raw bytes; don't declare a Pydantic body parameter here
    if not verify_github(body, request.headers.get("x-hub-signature-256"), SECRET):
        return text("invalid signature", 401)

    delivery = request.headers.get("x-github-delivery")
    if not delivery:
        return text("missing delivery id", 400)

    try:
        payload = json.loads(body)
    except ValueError:
        return text("invalid JSON", 400)

    if delivery in seen:
        return text("duplicate", 200)
    seen.add(delivery)

    background.add_task(handle_event, request.headers.get("x-github-event", ""), payload)
    return text("accepted", 202)  # background tasks run after this response is sent


def handle_event(event: str, payload: dict) -> None:
    print(event, payload.get("action", ""), payload.get("repository", {}).get("full_name", ""))

Run it and test it

Start the server (Flask on port 5000)
export GITHUB_WEBHOOK_SECRET="It's a test secret"
flask --app app run                # Flask: http://127.0.0.1:5000
fastapi dev main.py                # or FastAPI: http://127.0.0.1:8000

For FastAPI, use port 8000 in the URLs below. On macOS, AirPlay Receiver can hold port 5000; run Flask with --port 5001 if requests get a 403 from something that isn't your app.

In a second terminal, save this script as test-webhook.sh. It signs requests with openssl exactly like GitHub does and checks each status code against the table above. It's the same script for every tutorial in this series, so it also tells you whether a port to another framework behaves the same.

test-webhook.sh (bash, curl and openssl; on Windows run it in Git Bash or WSL)
#!/usr/bin/env bash
# Sends five deliveries to a GitHub webhook handler and checks each status code.
# Usage: GITHUB_WEBHOOK_SECRET='...' ./test-webhook.sh http://localhost:3000/webhooks/github
set -u
URL="${1:?usage: test-webhook.sh URL}"
SECRET="${GITHUB_WEBHOOK_SECRET:?set GITHUB_WEBHOOK_SECRET}"
BODY='{"action":"opened","issue":{"number":1347,"title":"Found a bug"},"repository":{"full_name":"octocat/Hello-World"}}'
ID="test-$(date +%s)-$$"
FAILED=0

sign() { printf '%s' "$1" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //'; }

send() { # body, signature ("" = none), delivery ID
  local args=(-s -o /dev/null -w '%{http_code}' -X POST "$URL"
    -H 'Content-Type: application/json' -H 'X-GitHub-Event: issues' -H "X-GitHub-Delivery: $3")
  [ -n "$2" ] && args+=(-H "X-Hub-Signature-256: sha256=$2")
  curl "${args[@]}" --data-binary "$1"
}

check() { # name, status received, status expected
  if [ "$2" = "$3" ]; then echo "ok   $1 ($2)"; else echo "FAIL $1: expected $3, got $2"; FAILED=1; fi
}

SIG=$(sign "$BODY")
check "valid delivery"             "$(send "$BODY" "$SIG" "$ID")" 202
check "same delivery again"        "$(send "$BODY" "$SIG" "$ID")" 200
check "body changed after signing" "$(send "${BODY/1347/1348}" "$SIG" "$ID-b")" 401
check "no signature"               "$(send "$BODY" "" "$ID-c")" 401
check "signed but not JSON"        "$(send "not json" "$(sign "not json")" "$ID-d")" 400
exit $FAILED
Run it with the same secret as the server
chmod +x test-webhook.sh
GITHUB_WEBHOOK_SECRET="It's a test secret" ./test-webhook.sh http://localhost:5000/webhooks/github
Expected output (exit code 0)
ok   valid delivery (202)
ok   same delivery again (200)
ok   body changed after signing (401)
ok   no signature (401)
ok   signed but not JSON (400)

The server logs issues opened octocat/Hello-World once, after the first response. A FAIL line names the check that broke; the mistakes table below lists what usually causes each one.

Receive real GitHub deliveries on localhost

GitHub won't send webhooks to localhost. Give it a HookWatcher endpoint instead, and let hwcli deliver each capture to your server byte for byte:

  1. Create a free HookWatcher account (or sign in) and create an endpoint; hwcli works with the endpoints in your account. Its URL looks like https://hookwatcher.com/<endpoint-id>.
  2. In the repository on GitHub, open Settings → Webhooks → Add webhook. Use the endpoint URL as the payload URL, application/json as the content type, and the same secret your server reads from GITHUB_WEBHOOK_SECRET.
  3. Run hwcli on your machine. --include-sensitive matters here: without it, signature headers are left out of local deliveries and every request fails with 401.
Deliver the endpoint's webhooks to your local server
hwcli login
hwcli listen <endpoint-id> --to http://localhost:5000/webhooks/github --include-sensitive

GitHub's ping arrives as soon as the webhook is saved, and your handler answers 202. To send a capture again, run hwcli replay <request-id>: it keeps the original X-GitHub-Delivery, so your handler should answer 200 duplicate. That's your deduplication tested with a real delivery. GitHub's signature has no timestamp, so replayed bytes still verify.

Common mistakes in Python webhook handlers

Python webhook problems
SymptomCauseFix
Every request is 401, but the secret is rightThe signature is computed over json.dumps(request.json): re-serialised JSON never matches the provider's bytesVerify request.get_data() (Flask) or await request.body() (FastAPI), then parse
TypeError: key: expected bytes or bytearray, but got 'str'The secret was passed as a strEncode it once: os.environ[...].encode()
Body is empty in Flaskrequest.form was read first on a form-encoded deliveryCall get_data() first, or use application/json in the webhook settings
422 Unprocessable Entity from FastAPIA Pydantic body parameter rejected the payload before your code ranRead Request directly; validate after the signature check
Duplicates slip through in productionSeveral gunicorn or uvicorn workers each have their own in-memory setStore delivery IDs in a database or Redis (see the FAQ)
413 Request Entity Too LargeThe proxy in front (NGINX's default client_max_body_size is 1 MB) or MAX_CONTENT_LENGTHAllow 25 MB for this route, GitHub's payload cap
GitHub shows "Timed out"The handler does the work before respondingHand it to a background task or queue (Celery, RQ, a table) and answer 202

See the exact bytes your Python handler must verify

Send a webhook to a free HookWatcher URL and read the raw body, every header and its SHA-256, the way Flask or FastAPI receives them.
Get a free webhook URL No account or card needed. Want to keep it? Create a free account

Frequently asked questions

Flask or FastAPI for webhooks?

Either works. The handler is a few lines in both; choose the one your app already uses. FastAPI's BackgroundTasks and Flask's threads are fine for light work after the response; anything that must not be lost belongs in a persistent queue.

How do I do this in Django?

Use verify.py unchanged with request.body (the raw bytes) in a view decorated with @csrf_exempt and @require_POST, since the provider can't send a CSRF token. The signature check replaces it.

Why not compare signatures with ==?

== stops at the first differing character, so timing can leak how much of a guess was right. hmac.compare_digest takes the same time either way, and GitHub's docs say to use a constant-time comparison.

Is an in-memory set of delivery IDs enough in production?

No. It's empty after a restart and separate in every process or server. Store processed IDs where all instances see them: a database table with a unique key on the delivery ID (insert, and treat a unique-constraint error as a duplicate) or Redis SET key value NX EX 259200. Three days covers GitHub's redelivery window.

Sources

More on GitHub webhooks

Headers, form-encoded payloads and delivery errors: GitHub webhook testing.