PushizoDocs
SDK guides

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

BuilderDefaultDescription
apiKey—hs_live_… API key (Bearer)
appId—App used when a call doesn't pass RequestOptions.appId
baseUrlhttps://api.pushizo.comAPI URL
timeout30 sTimeout per attempt
maxRetries3Maximum retries (policy)
autoIdempotencyKeytrueAutomatic UUID on calls that support Idempotency-Key
transportJdkHttpTransportCustom 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:

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 (ConnectException, UnknownHostException, HttpConnectTimeoutException, NoRouteToHostException)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, 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 classes

On this page