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.
Source: sdk/go. Models (models_gen.go) and services (resources_gen.go) are generated from api/openapi.yaml; authentication, retries, idempotency, pagination, and webhook signature verification are hand-written.
Installation
go get github.com/pushizo/pushizo-goUsage
import (
"context"
"log"
"os"
pushizo "github.com/pushizo/pushizo-go"
)
func main() {
ctx := context.Background()
hs, err := pushizo.NewClient(os.Getenv("HS_API_KEY"),
pushizo.WithAppID("app_…"),
// pushizo.WithBaseURL("http://localhost:4000"),
)
if err != nil {
log.Fatal(err)
}
// Send a notification: automatic UUID if no Idempotency-Key is given
res, err := hs.Notifications.Create(ctx, &pushizo.CreateNotificationDto{
Target: pushizo.CreateNotificationDtoTarget{IncludeAliases: map[string][]string{"external_id": {"user-42"}}},
Contents: map[string]string{"en": "Your order shipped", "tr": "Siparişiniz kargoya verildi"},
ThreadID: pushizo.String("orders"),
}, pushizo.WithIdempotencyKey("order-1001"))
if err != nil {
log.Fatal(err)
}
log.Println(res.ID, res.Status)
// Create/update a user
_, err = hs.Users.Upsert(ctx, &pushizo.UpsertUserDto{
ExternalID: pushizo.String("user-42"),
Tags: map[string]string{"plan": "pro"},
})
// Cursor pagination (Go 1.23 range-over-func)
for segment, err := range hs.Segments.ListAll(ctx, &pushizo.SegmentsListParams{Limit: pushizo.Int64(100)}) {
if err != nil {
log.Fatal(err)
}
log.Println(segment.Name)
}
// A single call for a different app
_, _ = hs.Apps.Get(ctx, pushizo.ForApp("app_diger"))
// SDK identity verification
_ = pushizo.IdentityHash(os.Getenv("HS_SDK_SECRET"), "user-42")
}Optional fields are pointers: pushizo.String, pushizo.Int64, pushizo.Bool, pushizo.Float64, or the generic pushizo.Ptr(v). Services are named after the OpenAPI tags (hs.Notifications, hs.Users, hs.Aliases, hs.Subscriptions, hs.Events, hs.Channels, hs.Segments, hs.Templates, hs.Campaigns, hs.Journeys, hs.InAppMessages, hs.Inbox, hs.Categories, hs.Preferences, hs.Suppressions, hs.Webhooks, hs.Analytics, hs.Exports, hs.Imports, hs.APIKeys, hs.Apps, hs.Organization). A/B winner: hs.Campaigns.SelectWinner, hs.InAppMessages.SelectWinner (InAppMessages.Winner is the old name and is deprecated). For endpoints without an SDK method and for non-JSON responses:
var csv string
err := hs.Request(ctx, "GET", "/v1/apps/{appId}/analytics/messages", url.Values{"format": {"csv"}}, nil, &csv)Settings
| Option | Default | Description |
|---|---|---|
WithAppID | — | App used when a call doesn't pass ForApp |
WithBaseURL | https://api.pushizo.com | API URL |
WithTimeout | 30 s | Timeout per attempt |
WithMaxRetries | 3 | Maximum retries (policy) |
WithAutoIdempotencyKey | true | Automatic UUID on calls that support Idempotency-Key |
WithHTTPClient | http.DefaultClient | Custom *http.Client |
Per call: ForApp, WithIdempotencyKey, WithHeader, WithRequestTimeout, WithRequestMaxRetries.
Errors
API errors are of type *pushizo.Error (StatusCode, Code, Message, RequestID, Details); the categories are ErrNetwork, ErrInvalidRequest (400/422), ErrAuthentication, ErrPermissionDenied, ErrNotFound, ErrConflict, ErrRateLimited, ErrServer.
_, err := hs.Notifications.Get(ctx, "msg_yok")
var apiErr *pushizo.Error
switch {
case errors.Is(err, pushizo.ErrNotFound):
// 404
case errors.Is(err, pushizo.ErrRateLimited):
// 429 (retries exhausted)
case errors.As(err, &apiErr) && apiErr.Code == pushizo.CodeNoRecipients:
// 422 HS_NO_RECIPIENTS
}Retry policy
Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most WithMaxRetries 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 (*net.DNSError, *net.OpError in the dial/proxyconnect phase: connection refused, connect timeout) | 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(ctx, body, pushizo.WithIdempotencyKey("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
http.HandleFunc("/hooks/pushizo", func(w http.ResponseWriter, r *http.Request) {
payload, _ := io.ReadAll(r.Body) // raw body
events, err := pushizo.ConstructWebhookEvents(payload,
r.Header.Get(pushizo.WebhookSignatureHeader),
[]string{os.Getenv("HS_WEBHOOK_SECRET")}, // during rotation, pass the old and new secrets together
nil) // default tolerance is 5 min
if err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
for _, ev := range events { // single or batch body
_ = ev.Type // deduplicate using Pushizo-Event-Id
}
w.WriteHeader(http.StatusNoContent)
})For verification only, pushizo.VerifyWebhookSignature(...) returns WebhookVerifyResult{OK, Timestamp, Reason}. Event types: Webhooks.
Development
go vet ./... && go test ./... # inside sdk/go
node sdk/scripts/generate-server-sdks.mjs --lang go # at the repo root; regenerates the *_gen.go filesPython SDK
pushizo (PyPI) — Python 3.9+, httpx; models and resource methods generated from OpenAPI, retries, idempotency, pagination, webhook signature verification.
Java SDK
com.pushizo:pushizo-java — Java 17+, java.net.http and Jackson; generated models, parameter classes, and resources; retries, idempotency, pagination, webhook signature verification.