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 pushizoUsage
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
| Parameter | Default | Description |
|---|---|---|
api_key | — | hs_live_… API key (Bearer) |
app_id | None | App used when a call doesn't pass app_id= |
base_url | https://api.pushizo.com | API URL |
timeout | 30 | Timeout per attempt (s) |
max_retries | 3 | Maximum retries (policy) |
auto_idempotency_key | True | Automatic 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:
| Condition | GET, HEAD, OPTIONS, PUT, DELETE | POST, PATCH |
|---|---|---|
429 | Retried | Retried (the request was rejected before processing) |
5xx, timeout, connection dropped after sending | Retried | Only with an Idempotency-Key |
Request never sent (httpx.ConnectError (connection refused, DNS error), ConnectTimeout, PoolTimeout) | Retried | Retried |
Other 4xx | Not retried | Not 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 "", 204If 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/resourcesPHP SDK
pushizo/pushizo-php — PHP ≥ 8.1, only ext-curl and ext-json; notifications, users, events, webhook signature verification, journeys, and the entire public API. Laravel example included.
Go SDK
github.com/pushizo/pushizo-go — Go 1.23+, standard library only; generated models and services, retries, idempotency, range-over-func pagination, webhook signature verification.