Python webhooks: Flask and FastAPI handlers that verify signatures
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:
- verifies
X-Hub-Signature-256over the raw body bytes, before anything parses them, and answers401if it doesn't match; - requires an
X-GitHub-DeliveryID and parses the JSON (400if either is missing or broken); - skips a delivery ID it has already processed with a
200, so GitHub records success and the event runs once; - answers
202straight away and does the work after the response, because GitHub gives up after 10 seconds.
| Request | Status | Body |
|---|---|---|
| Valid signature, new delivery | 202 | accepted |
| Same delivery ID again | 200 | duplicate |
| Missing or wrong signature, or body changed after signing | 401 | invalid signature |
| Valid signature, no delivery ID or not JSON | 400 | missing 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
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.
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:
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()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.
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.
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
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.
#!/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 $FAILEDchmod +x test-webhook.sh GITHUB_WEBHOOK_SECRET="It's a test secret" ./test-webhook.sh http://localhost:5000/webhooks/github
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:
- 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>. - In the repository on GitHub, open Settings → Webhooks → Add webhook. Use the endpoint URL as the payload URL,
application/jsonas the content type, and the same secret your server reads fromGITHUB_WEBHOOK_SECRET. - Run hwcli on your machine.
--include-sensitivematters here: without it, signature headers are left out of local deliveries and every request fails with401.
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
| Symptom | Cause | Fix |
|---|---|---|
| Every request is 401, but the secret is right | The signature is computed over json.dumps(request.json): re-serialised JSON never matches the provider's bytes | Verify 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 str | Encode it once: os.environ[...].encode() |
| Body is empty in Flask | request.form was read first on a form-encoded delivery | Call get_data() first, or use application/json in the webhook settings |
| 422 Unprocessable Entity from FastAPI | A Pydantic body parameter rejected the payload before your code ran | Read Request directly; validate after the signature check |
| Duplicates slip through in production | Several gunicorn or uvicorn workers each have their own in-memory set | Store delivery IDs in a database or Redis (see the FAQ) |
| 413 Request Entity Too Large | The proxy in front (NGINX's default client_max_body_size is 1 MB) or MAX_CONTENT_LENGTH | Allow 25 MB for this route, GitHub's payload cap |
| GitHub shows "Timed out" | The handler does the work before responding | Hand it to a background task or queue (Celery, RQ, a table) and answer 202 |
See the exact bytes your Python handler must verify
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
- Python: hmac (compare_digest)
- Flask API: Request.get_data
- FastAPI: Using the Request directly
- FastAPI: Background tasks
- GitHub Docs: Validating webhook deliveries
More on GitHub webhooks
Headers, form-encoded payloads and delivery errors: GitHub webhook testing.