PushizoDocs
SDK guides

Python SDK

pushizo (PyPI) — Python 3.9+, httpx; models and resource methods generated from OpenAPI, retries, idempotency, pagination, webhook signature verification.

Source: sdk/python. Models and resource methods are generated from api/openapi.yaml (npm run sdk:generate); authentication, retries, idempotency, pagination, and webhook signature verification live in a hand-written layer.

Installation

pip install pushizo

Usage

import os
from pushizo import Pushizo

hs = Pushizo(api_key=os.environ["HS_API_KEY"], app_id="app_…")  # locally: base_url="http://localhost:4000"

# Send a notification (automatic UUID if idempotency_key isn't given; retries reuse the same key)
res = hs.notifications.create(
    {
        "target": {"include_aliases": {"external_id": ["user-42"]}},
        "contents": {"en": "Your order shipped", "tr": "Siparişiniz kargoya verildi"},
    },
    idempotency_key="order-1001",
)
print(res["id"], res["status"])

# Create/update a user and add a subscription
hs.users.upsert({"external_id": "user-42", "tags": {"plan": "pro"}})
hs.users.add_subscription("external_id", "user-42", {"channel": "email", "token": "ayse@pushizo.com"})

# Cursor pagination: iterates over all pages
for segment in hs.segments.list_all(limit=100):
    print(segment["name"])

# A single call for a different app
hs.apps.get(app_id="app_diger")

# SDK identity verification: identity_hash = HMAC-SHA256(sdk_secret, external_id)
identity_hash = Pushizo.identity_hash(os.environ["HS_SDK_SECRET"], "user-42")

At runtime, models are plain dicts; types show up in your editor through the TypedDicts in pushizo._generated.models (CreateNotificationDto, Message …). Resource names match the OpenAPI tags (notifications, users, aliases, subscriptions, events, channels, segments, templates, campaigns, journeys, in_app_messages, inbox, categories, preferences, suppressions, webhooks, analytics, exports, imports, api_keys, apps, organization); method names are snake_case (campaigns.variant_stats, campaigns.select_winner, in_app_messages.select_winner, organization.usage; in_app_messages.winner is the old name and is deprecated). For endpoints without an SDK method and for non-JSON responses:

hs.request("GET", "/v1/apps/app_…/analytics/messages", query={"format": "csv"})

Settings

ParameterDefaultDescription
api_key—hs_live_… API key (Bearer)
app_idNoneApp used when a call doesn't pass app_id=
base_urlhttps://api.pushizo.comAPI URL
timeout30Timeout per attempt (s)
max_retries3Maximum retries (policy)
auto_idempotency_keyTrueAutomatic UUID on calls that support Idempotency-Key
http_client—Custom httpx.Client (proxy, TLS)

You can also configure each call with request_options={"timeout": 5, "max_retries": 0, "headers": {...}}.

Errors

Retries follow the policy below. Permanent errors derive from PushizoError and carry status, code (HS_…), request_id, and details:

from pushizo import ErrorCode, NotFoundError, RateLimitError, PushizoError

try:
    hs.notifications.get("msg_yok")
except NotFoundError as e:
    print(e.code == ErrorCode.NOT_FOUND, e.request_id)
except RateLimitError:
    ...
except PushizoError as e:  # InvalidRequestError, AuthenticationError, PermissionDeniedError, ConflictError, ServerError, NetworkError
    print(e.status, e.code, e.message)

Retry policy

Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most max_retries times. To avoid double-processing requests that aren't safe to repeat on the server, the rule depends on the HTTP method:

ConditionGET, HEAD, OPTIONS, PUT, DELETEPOST, PATCH
429RetriedRetried (the request was rejected before processing)
5xx, timeout, connection dropped after sendingRetriedOnly with an Idempotency-Key
Request never sent (httpx.ConnectError (connection refused, DNS error), ConnectTimeout, PoolTimeout)RetriedRetried
Other 4xxNot retriedNot retried

On a 5xx or a network error after sending, the server may have processed the request; retrying a POST/PATCH without a key can produce a duplicate notification or record. notifications.create and users.upsert generate an automatic UUID when no key is given (unless automatic keys are disabled), so these two calls are safe to retry. If you want another POST/PATCH call to be retried as well, pass the key yourself: hs.events.send(body, request_options={"idempotency_key": f"evt-{id}"}). Retries send the same key; the API answers a repeat with the same key within 24 hours with the original response.

Webhook signature verification

import os
from flask import Flask, request
from pushizo import WebhookSignatureError, construct_webhook_events

app = Flask(__name__)

@app.post("/hooks/pushizo")
def pushizo_hook():
    try:
        events = construct_webhook_events(
            request.get_data(),                         # raw body
            request.headers.get("Pushizo-Signature"),
            os.environ["HS_WEBHOOK_SECRET"],            # during rotation you can pass [old, new]
        )
    except WebhookSignatureError as e:
        return e.reason, 400
    for event in events:                              # single or batch body
        ...                                           # deduplicate using Pushizo-Event-Id
    return "", 204

If the timestamp is older than 5 minutes (tolerance_seconds), the request is treated as a replay and rejected. Event types and body: Webhooks.

Development

pip install -e ".[dev]" && pytest                        # inside sdk/python
node sdk/scripts/generate-server-sdks.mjs --lang python  # at the repo root; regenerates models/resources

On this page