hookon

Tier-2 reconciliation client for Hookon.

Call hookon.ack(event.id) inside your webhook handler. Hookon polls your provider's deliveries API and cross-references your acks; an event the provider says was delivered but that never acked here is a silent drop.

Install

pip install hookon

Zero runtime dependencies. Works on Python 3.8 and up, on sync and async web frameworks (Flask, Django, FastAPI, Starlette, Quart, and others).

Quickstart

from hookon import Hookon

hookon = Hookon(api_key="pk_live_xxxxxxxxxxxx", endpoint="prod-stripe-handler")

# Flask example
@app.post("/webhooks/stripe")
def stripe_webhook():
    event = verify_stripe_signature(request)
    handle_event(event)
    hookon.ack(event["id"])       # one line
    return "", 200

The call is synchronous and never raises. Acks are batched in a daemon thread and sent in the background (50 per batch or 2 seconds, whichever first).

API

Hookon(
    api_key: str,
    *,
    endpoint: str | None = None,
    base_url: str = "https://api.hookon.dev",
    fetcher: Callable[[str, dict, bytes, float], int] | None = None,
)

• hookon.ack(event_id, *, received_at=None) — queue an ack. Never raises.
• hookon.flush() — force-send any pending acks and wait for the in-flight request to settle. Useful in serverless handlers before the process exits.
• hookon.close() — stop accepting new acks and flush. Safe to call at shutdown; subsequent ack() calls become no-ops.

Behaviour

• Idempotent. Sending the same event_id twice is a no-op on the server. Hookon keys on (workspace, provider_event_id).
• Forward-tolerant. If the SDK acks an event before our 60-second poller has seen it, we create a placeholder row; the next poll heals it with the real event metadata.
• Silent on failure. Auth and transport errors are logged at most once per failure mode via the hookon logger (and written to stderr for uncustomised setups). Further failures of the same kind are suppressed.
• Never raises from ack(). A broken Hookon must never break your webhook handler.

Development

pip install -e '.[test]'
pytest

Links

• Docs: https://hookon.dev/docs/sdk/python
• Dashboard: https://hookon.dev
• Issues: https://github.com/hookondev/sdk-python/issues

License

MIT