PushizoDocs
SDK guides

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-go

Usage

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

OptionDefaultDescription
WithAppID—App used when a call doesn't pass ForApp
WithBaseURLhttps://api.pushizo.comAPI URL
WithTimeout30 sTimeout per attempt
WithMaxRetries3Maximum retries (policy)
WithAutoIdempotencyKeytrueAutomatic UUID on calls that support Idempotency-Key
WithHTTPClienthttp.DefaultClientCustom *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:

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 (*net.DNSError, *net.OpError in the dial/proxyconnect phase: connection refused, connect timeout)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(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 files

On this page