Python SDK

propper-click is the server-side SDK for Propper Click in Python. Use it from Django, FastAPI, Flask, or any other Python backend.

---

Install

pip install propper-click

Requires Python 3.9+.

---

Quick start

import os
from propper_click import PropperClick, ClickClientConfig

click = PropperClick(ClickClientConfig(api_key=os.environ["PROPPER_API_KEY"]))

receipt = click.acceptances.create({
    "templateVersionId": "tv_...",
    "deploymentId":      "dep_...",
    "checksum":          "sha256-hex...",
    "consentMethod":     "BUTTON",
    "email":             "user@example.com",
})

print("Receipt:", receipt["receiptId"])

click.close()

Use as a context manager to auto-close:

with PropperClick(ClickClientConfig(api_key=KEY)) as click:
    click.acceptances.create({...})

---

Authentication

# API key (default when api_key is set)
PropperClick(ClickClientConfig(api_key="sk_live_..."))

# OAuth bearer
PropperClick(ClickClientConfig(auth_type="bearer", bearer_token="eyJ..."))

---

Resources

Resource	Methods
acceptances	create(payload, idempotency_key=...)
templates	list, get, create, update, delete
deployments	list, get, create
render	by_deployment(id), by_route(domain=, path=, ...)
verification	verify_receipt({"receiptJson": ...})

---

Idempotency

click.acceptances.create(payload, idempotency_key=request_id)

The SDK auto-generates a UUID v4 when no key is provided. The server replays a cached response for repeats within 24 hours.

---

Webhook verification (FastAPI)

from fastapi import FastAPI, HTTPException, Request
from propper_click import verify_webhook_signature, WebhookVerificationError

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    body = await request.body()  # raw bytes BEFORE parsing
    try:
        verify_webhook_signature(
            body=body,
            signature_header=request.headers.get("X-Propper-Signature"),
            secrets=os.environ["PROPPER_WEBHOOK_SECRET"],
        )
    except WebhookVerificationError as err:
        raise HTTPException(status_code=400, detail=f"invalid signature ({err.reason})")
    # ... parse + handle
    return {"status": "ok"}

See webhook verification for full signature spec.

---

Error handling

from propper_click import (
    PropperClickAuthError,
    PropperClickRateLimitError,
    PropperClickValidationError,
)

try:
    click.acceptances.create(payload)
except PropperClickAuthError:
    # rotate key
    ...
except PropperClickRateLimitError as e:
    # back off e.retry_after_seconds
    ...
except PropperClickValidationError:
    # fix payload
    ...

---

Configuration reference

ClickClientConfig(
    api_key="sk_live_...",                  # or bearer_token + auth_type="bearer"
    environment="production",
    base_url="https://api.propper.ai/v1/click",
    max_retries=3,
    timeout_seconds=30.0,
    debug=False,
)