Building Correct Payment Infrastructure: Webhooks, Reconciliation, and Records

Payments code has a strange property: most of it is boring, and the boring parts are exactly where money goes missing. Webhook handlers, money arithmetic, reconciliation jobs — the unglamorous plumbing every team rebuilds, slightly wrong, at every company. After close to two decades working on payment systems, I kept running into the same three mistakes, each cheap to make and expensive to find. So I wrote three small, dependency-free, MIT-licensed tools that each fix one.

This post walks through the failure modes and the fixes. The code below is illustrative, but it mirrors what the tools actually do.

Failure mode 1: webhooks you can't actually trust

A webhook is an unauthenticated POST from the internet until you prove otherwise. The naive handler trusts the body. The slightly-better handler verifies a signature but still gets it wrong in two ways: it compares the signature with a normal string equality, which leaks timing information an attacker can exploit byte by byte, and it has no replay protection, so a captured-and-resent event is accepted again.

# Anti-pattern: trusts the payload, and == leaks timing.
@app.post("/webhook")
def handle(req):
    event = json.loads(req.body)          # no verification at all
    if req.headers["X-Sig"] == expected:  # timing-unsafe compare
        process(event)                    # and no replay protection

The correct version does three things: it rejects events whose timestamp is outside a tolerance window (replay protection), it recomputes the HMAC over the signed payload, and it compares using a constant-time function that does not exit early on the first differing byte.

import hmac, hashlib, time

def verify(secret: bytes, payload: bytes, signature: str,
           timestamp: str, tolerance: int = 300) -> bool:
    # 1) replay protection: reject stale or future-dated events
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    # 2) recompute the HMAC over "timestamp.payload"
    signed   = f"{timestamp}.".encode() + payload
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
    # 3) constant-time compare -- no early-exit timing leak
    return hmac.compare_digest(expected, signature)

Even with this, a replay inside the tolerance window slips through, so you also de-duplicate on the provider's event ID. This is the whole job of PayHooks: constant-time signature checks plus replay protection — timestamp windows and event-ID de-duplication — with presets for Stripe, Slack, GitHub, Shopify, Razorpay, Square, and Adyen, each of which formats its signatures a little differently. It's pure Python, zero third-party dependencies, usable as a CLI or a library.

Failure mode 2: representing money as a float

The single most common money bug is storing or computing currency in binary floating point. Floats can't represent most decimal fractions exactly, so the errors are small, silent, and cumulative — until a reconciliation report is off by a cent nobody can explain.

>>> 0.1 + 0.2
0.30000000000000004           # float money is wrong money

from decimal import Decimal, ROUND_HALF_UP
unit  = Decimal("19.99")
total = (unit * 3).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
# total == Decimal("59.97"), every cent accounted for and rounding explicit

The fix is to use exact decimal arithmetic (or integer minor units) everywhere money is touched, and to make rounding a deliberate, named decision rather than an accident of the hardware. OpenRecon uses Decimal-precise money throughout, so two amounts that should be equal compare equal, and discrepancies that appear are real rather than artifacts of float drift.

Failure mode 3: reconciliation that only checks totals

Reconciliation is where the first two failures come home to roost, and it has a structural trap of its own: comparing totals. If one record is over-counted and another under-counted by the same amount, the sums agree while the records are wrong. A robust reconciler matches at the record level, and it does so in two phases — first an exact match on a shared key, then a heuristic pass over the leftovers — classifying what it cannot match rather than hiding it.

def reconcile(ledger, processor):
    index = {r.id: r for r in processor}
    matched, exceptions = [], []

    # phase 1 -- exact match on the shared key
    for L in ledger:
        P = index.pop(L.id, None)
        if P is None:
            exceptions.append(("missing_in_processor", L))
        elif P.amount != L.amount:                  # exact Decimal compare
            exceptions.append(("amount_mismatch", L, P))
        else:
            matched.append((L, P))

    # phase 2 -- match leftovers heuristically on (amount, date) in a window;
    # anything still unmatched is a real exception, not a rounding ghost
    for P in index.values():
        exceptions.append(("unrecorded_charge", P))
    return matched, exceptions

That two-phase shape — key match, then heuristic — is what OpenRecon implements across processors, gateways, and an internal ledger. It ships with six processor presets, keeps money in Decimal, and is built to run in CI so a reconciliation break fails a pipeline instead of surfacing in a month-end report. The exceptions it surfaces are the ones that matter: fee discrepancies, missing settlements, and unrecorded charges.

And then: records you can defend

The last mile of payments work is proof. When a dispute or an audit arrives, you need a record of what a page or a report showed at a point in time. PagePDF handles that unglamorous step: a Manifest V3 Chrome and Edge extension that saves any web page as a professional PDF — selectable text via the Chrome DevTools Protocol, or a full-page screenshot through a hand-written PDF encoder — stamped with the date and time, the source URL, and page numbers. It runs entirely in the browser, with nothing sent anywhere.

The through-line

Read together, the three tools trace the lifecycle of a payment event: ingest it safely (PayHooks), reconcile it correctly (OpenRecon), and archive it defensibly (PagePDF). The shared philosophy is deliberate. Each is free and open source under the MIT license, carries zero third-party dependencies, runs locally with no servers or data collection, and is engineered from first principles so you can read every line and trust it.

None of this is novel computer science. It's just the careful version of work most teams do quickly — and in payments, careful is the whole job.

The repositories are open, and feedback and issues are welcome:

PayHooks — https://github.com/Naresh-Paturi-Community/payhooks
OpenRecon — https://github.com/Naresh-Paturi-Community/openrecon
PagePDF — https://github.com/Naresh-Paturi-Community/pagepdf

If you've shipped webhook or reconciliation code that bit you, I'd genuinely like to hear how — open an issue or leave a comment.

推荐订阅源