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.
Source: sdk/java. Models (com.pushizo.models), parameter classes (com.pushizo.params), and resources (com.pushizo.resources) are generated from api/openapi.yaml; authentication, retries, idempotency, pagination, and webhook signature verification are hand-written.
Installation
<dependency>
<groupId>com.pushizo</groupId>
<artifactId>pushizo-java</artifactId>
<version>0.1.0</version>
</dependency>implementation("com.pushizo:pushizo-java:0.1.0")Usage
import com.pushizo.Pushizo;
import com.pushizo.RequestOptions;
import com.pushizo.models.*;
import com.pushizo.params.SegmentsListParams;
import java.util.List;
import java.util.Map;
Pushizo hs = Pushizo.builder()
.apiKey(System.getenv("HS_API_KEY"))
.appId("app_…")
// .baseUrl("http://localhost:4000")
.build();
// Send a notification: automatic UUID if no Idempotency-Key is given
CreateNotificationResult res = hs.notifications().create(
new CreateNotificationDto()
.target(new CreateNotificationDtoTarget().includeAliases(Map.of("external_id", List.of("user-42"))))
.contents(Map.of("en", "Your order shipped", "tr", "Siparişiniz kargoya verildi")),
RequestOptions.builder().idempotencyKey("order-1001").build());
System.out.println(res.getId() + " " + res.getStatus());
// Create/update a user
hs.users().upsert(new UpsertUserDto().externalId("user-42").tags(Map.of("plan", "pro")));
// Cursor pagination: pages are loaded lazily
for (Segment segment : hs.segments().listAll(new SegmentsListParams().limit(100L))) {
System.out.println(segment.getName());
}
// A single call for a different app
hs.apps().get(RequestOptions.forApp("app_diger"));
// SDK identity verification
String identityHash = Pushizo.identityHash(System.getenv("HS_SDK_SECRET"), "user-42");Model fields are used through fluent setters (.contents(...)) and getX() getters; null fields aren't sent, and unknown fields are ignored. Resources: 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, @Deprecated). For endpoints without an SDK method or for non-JSON responses, use hs.request("GET", "/v1/apps/{appId}/analytics/messages", Map.of("format", "csv"), null, null) (returns the body as text).
Settings
| Builder | Default | Description |
|---|---|---|
apiKey | — | hs_live_… API key (Bearer) |
appId | — | App used when a call doesn't pass RequestOptions.appId |
baseUrl | https://api.pushizo.com | API URL |
timeout | 30 s | Timeout per attempt |
maxRetries | 3 | Maximum retries (policy) |
autoIdempotencyKey | true | Automatic UUID on calls that support Idempotency-Key |
transport | JdkHttpTransport | Custom transport (e.g. new JdkHttpTransport(customHttpClient)) |
Per call: RequestOptions.builder().appId(..).idempotencyKey(..).timeout(..).maxRetries(..).header(..).
Errors
Permanent errors are subclasses of PushizoException (unchecked): getStatus(), getCode(), getRequestId(), getDetails().
try {
hs.notifications().get("msg_yok");
} catch (NotFoundException e) {
// 404
} catch (InvalidRequestException e) {
if (ErrorCodes.NO_RECIPIENTS.equals(e.getCode())) { /* 422 */ }
} catch (PushizoException e) {
// AuthenticationException, PermissionDeniedException, ConflictException, RateLimitException, ServerException, NetworkException
}Retry policy
Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most maxRetries 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 (ConnectException, UnknownHostException, HttpConnectTimeoutException, NoRouteToHostException) | 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, RequestOptions.builder().idempotencyKey("evt-" + id).build()). 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 com.pushizo.WebhookEvent;
import com.pushizo.WebhookSignatureException;
import com.pushizo.Webhooks;
byte[] payload = request.getInputStream().readAllBytes(); // raw body
try {
List<WebhookEvent> events = Webhooks.constructEvents(payload,
request.getHeader(Webhooks.SIGNATURE_HEADER),
List.of(System.getenv("HS_WEBHOOK_SECRET"))); // during rotation: old + new secret
for (WebhookEvent event : events) { // single or batch body
// deduplicate using event.getId(); event.getType(), event.getData()
}
response.setStatus(204);
} catch (WebhookSignatureException e) {
response.setStatus(400); // e.getReason()
}For verification only, Webhooks.verifySignature(...) returns WebhookVerifyResult(ok, timestamp, reason). Event types: Webhooks.
Development
mvn test # inside sdk/java
node sdk/scripts/generate-server-sdks.mjs --lang java # at the repo root; regenerates the generated classesGo 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.
.NET SDK
Pushizo (NuGet) — .NET 8, HttpClient and System.Text.Json; generated models and resources, retries, idempotency, IAsyncEnumerable pagination, webhook signature verification.