Handling incoming webhooks from payment processors, source control platforms, and SaaS providers requires strict payload integrity. When receiving a webhook, your application usually verifies a cryptographic signature—such as GitHub's X-Hub-Signature-256 or Stripe's signature header—to confirm that the request actually came from the provider and has not been altered in transit.
However, unexpected downstream outages or temporary database connection errors often require your system to buffer and retry these incoming webhooks. A common bug occurs during this retry cycle: applications parse incoming JSON into native dictionaries, store that parsed data, and later serialize it back into a string or bytes when replaying the request.
This guide explains the underlying problem of payload mutation during webhook persistence and demonstrates how to use rawhook_webhook_retry_helper.py to capture, verify, and store raw payloads without invalidating cryptographic signatures.
The Problem: Serialization Drift and Stream Exhaustion
Cryptographic signatures are computed across the exact sequence of bytes transmitted across the wire. If a single byte changes, verification fails. When handling webhooks, two architectural issues frequently disrupt signature verification:
1. Payload Mutation Through Re-Serialization
When an application receives raw bytes and parses them into memory using standard JSON decoders, several transformations occur:
- Key Reordering: Dictionary keys in parsed structures do not guarantee the original wire order.
-
Floating-Point Drift: Numeric types like
10.0or scientific notation might be parsed and re-encoded differently (e.g.,10or1.0e1). -
Whitespace and Escaping: Indentation, spaces after colons, newline placement, and Unicode escape sequences (such as
\u0026versus&) are lost or altered upon re-serialization.
If you attempt to recalculate or forward a re-serialized JSON payload, its SHA-256 digest will differ from the original digest, rendering signatures invalid.
2. WSGI Stream Exhaustion
In Python WSGI servers, request bodies are delivered via an input stream stored in environ['wsgi.input']. Because network streams are readable only once, consuming the stream to compute a signature or write an audit log empties the stream. Downstream web framework components then attempt to read from environ['wsgi.input'] and receive empty bytes, failing with empty request body errors.
Install & Usage
The tool is implemented in a single self-contained Python file. It has no external dependencies and uses only Python standard library modules (argparse, sqlite3, hmac, hashlib, http.client, io, and urllib.parse). You do not need to run pip install for any third-party packages.
Installation
Save the source code directly as rawhook_webhook_retry_helper.py in your project directory:
# Verify the script executes cleanly using the Python interpreter
python rawhook_webhook_retry_helper.py --help
Usage as a Python Library
You can import the module directly into your existing Python backend to capture WSGI inputs, verify signatures against raw bytes, and persist records in SQLite.
from rawhook_webhook_retry_helper import (
capture_wsgi_environ,
verify_signature,
RawHookRecord,
RawHookStorage,
TamperDetectedError,
)
# 1. Capture raw payload and headers from a WSGI environment
# This rewinds environ['wsgi.input'] so your framework can still read it
raw_body, headers = capture_wsgi_environ(environ)
# 2. Verify signature before processing
secret = b"webhook_secret_key"
signature_header = headers.get("x-hub-signature-256", "")
is_valid = verify_signature(
raw_body=raw_body,
secret=secret,
header_value=signature_header,
scheme="github",
)
if is_valid:
# 3. Store raw bytes safely in SQLite for retry handling
storage = RawHookStorage(db_path="webhooks.db")
record = RawHookRecord(
record_id="evt_1001",
target_url="/internal/webhook/handler",
method="POST",
headers=headers,
raw_body=raw_body,
)
storage.save(record)
How It Works
The tool relies on four core components to guarantee that raw bytes remain intact throughout the ingestion and persistence pipeline.
1. Rewindable Stream Wrapper
To resolve WSGI stream exhaustion, RewindableStreamWrapper reads the input stream up to the declared CONTENT_LENGTH, stores the raw bytes in an internal memory buffer, and re-populates the environment with a seekable io.BytesIO instance:
class RewindableStreamWrapper:
"""
Prevents framework-specific stream exhaustion (e.g. WSGI environ['wsgi.input']
or ASGI receive streams). Reads the raw stream into an internal memory buffer,
computes integrity checksums, and replaces the stream with a rewindable buffer
so downstream framework consumers can still read it cleanly.
"""
def __init__(self, original_stream: Any, content_length: Optional[int] = None) -> None:
self.raw_bytes = b""
if hasattr(original_stream, "read"):
if content_length is not None and content_length >= 0:
self.raw_bytes = original_stream.read(content_length)
else:
self.raw_bytes = original_stream.read()
elif isinstance(original_stream, (bytes, bytearray)):
self.raw_bytes = bytes(original_stream)
else:
raise TypeError("original_stream must provide a read() method or be raw bytes")
self.buffer = io.BytesIO(self.raw_bytes)
2. Tamper-Evident RawHookRecord
When initializing a RawHookRecord, the class enforces binary input (bytes or bytearray). It automatically computes a SHA-256 checksum over the byte sequence. If the payload is modified while in transit or in memory, tamper_check() detects the mismatch and raises a TamperDetectedError:
computed_sha = hashlib.sha256(self.raw_body).hexdigest()
if content_sha256 is None:
self.content_sha256 = computed_sha
else:
self.content_sha256 = content_sha256
if self.content_sha256 != computed_sha:
raise TamperDetectedError(
f"Integrity check failed: expected {self.content_sha256}, calculated {computed_sha}"
)
3. Native Signature Verification
The script supports GitHub (sha256= or sha1=) and Stripe timestamped signatures (t=...,v1=...). It handles timestamp extraction and compares signatures using hmac.compare_digest to prevent timing attacks:
def compute_github_signature(raw_body: bytes, secret: bytes) -> str:
"""Computes standard sha256=<hex> HMAC signature."""
mac = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
return f"sha256={mac}"
For Stripe signatures, the verification logic inspects tolerance windows and computes HMAC over the concatenated timestamp and raw body:
payload = f"{ts}.".encode("utf-8") + raw_body
expected_mac = hmac.new(secret, payload, hashlib.sha256).hexdigest()
for sig in signatures:
if hmac.compare_digest(expected_mac, sig):
return True
4. Binary BLOB Storage in SQLite
Headers and payloads are stored directly in SQLite without translating JSON data into string encodings that could mutate formatting. Headers are parsed into a case-insensitive map, serialized to colon-delimited lines, and the payload is saved as a raw BLOB using sqlite3.Binary:
cursor.execute(
"""
INSERT OR REPLACE INTO webhooks (
record_id, target_url, method, headers_raw,
raw_body, content_sha256, created_at, retry_count, status, last_error
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
record.record_id,
record.target_url,
record.method,
headers_serialized,
sqlite3.Binary(record.raw_body),
record.content_sha256,
record.created_at,
record.retry_count,
record.status,
record.last_error,
),
)
Limitations
Before deploying this script, note the limitations present in its current implementation:
-
Built-in Scheme Support:
verify_signatureonly implements verification schemes for GitHub and Stripe formats. If your provider uses a different header structure or signing format, you must write custom verification code. -
Header Serialization: Header storage serializes headers into single-line
key:valuepairs separated by newline characters (\n). Multi-line header values or values containing literal newline characters will have those characters stripped. -
In-Memory Buffering:
RewindableStreamWrapperloads the entire raw request into an in-memoryio.BytesIObuffer. While suitable for standard webhooks, it is not designed to stream multi-gigabyte payloads. -
In-Memory SQLite Concurrency: When using
:memory:databases, state is isolated to the specific database connection created at instantiation and cannot be shared across multiple processes.
FAQ
Can I re-serialize JSON payloads using json.dumps instead of saving raw bytes?
No. Standard JSON encoders do not guarantee preservation of original key ordering, whitespace padding, or Unicode escape patterns. Any change to the serialized byte string invalidates HMAC verification computed against the original transmission.
What happens if a payload is modified after being saved?
When tamper_check() runs, or when a record is loaded and verified, RawHookRecord compares the SHA-256 digest of self.raw_body to the stored content_sha256. If the bytes do not match, it raises a TamperDetectedError.
Does RawHook require installing external database drivers or HTTP libraries?
No. The implementation relies entirely on Python's built-in standard library, utilizing sqlite3 for local persistence and hmac/hashlib for signature verification. No third-party packages need to be installed.
Full version, tests and changelog: RawHook Webhook Retry Helper on PyForge.
Top comments (0)