# Java (https://sockudo.io/docs/server-sdks/java) > Publish events, sign channel auth, validate webhooks, read history, mutate versioned messages, and manage push from Java and Spring Boot backends, with synchronous and CompletableFuture clients. `sockudo-http-java` is the official Java client for the Sockudo HTTP API. It ships a synchronous client (`io.sockudo.rest.Sockudo`, built on Apache HttpClient 4.5) and an asynchronous client (`io.sockudo.rest.SockudoAsync`, built on AsyncHttpClient 3) with the same methods, and is meant to run only on trusted backends that hold your app secret. What it does in Java: - Signed HTTP publishing to one channel, up to 100 channels, or a batch of events. - Automatic idempotency keys plus built-in retries for network errors and `5xx` responses. - Private, presence, and encrypted channel authorization. - Webhook signature validation and tolerant webhook parsing. - Durable history, presence history, and presence snapshots. - Versioned message reads and mutations (get, versions, update, delete, append) and annotations. - Push device registrations, channel subscriptions, publish, scheduling, publish status, and Apple Live Activity broadcast channels. - Generic signed `get`, `post`, and `delete` helpers, plus `signedUri` for your own HTTP client. ## Install The library targets **Java 11** bytecode and is tested on Java 11, 17, and 21. Install it from Maven Central: ```xml title="pom.xml" io.sockudo sockudo-http-java 2.2.0 ``` ```kotlin title="build.gradle.kts" implementation("io.sockudo:sockudo-http-java:2.2.0") ``` Apache HttpClient, AsyncHttpClient, and Gson are exposed as `api` dependencies because they appear in public method signatures. For local development against this monorepo, publish the package to your local Maven repository from `server-sdks/sockudo-http-java`: ```bash title="Terminal" ./gradlew publishToMavenLocal ``` ## Configure the client Create one client and expose it as a Spring bean. Spring resolves `${SOCKUDO_APP_SECRET}` and the other placeholders from environment variables, so credentials stay out of source control: ```java title="SockudoConfig.java" @Configuration public class SockudoConfig { @Bean public Sockudo sockudo( @Value("${SOCKUDO_APP_ID}") String appId, @Value("${SOCKUDO_APP_KEY}") String key, @Value("${SOCKUDO_APP_SECRET}") String secret, @Value("${SOCKUDO_HOST:127.0.0.1:6001}") String host, @Value("${SOCKUDO_TLS:false}") boolean tls) { Sockudo sockudo = new Sockudo(appId, key, secret); sockudo.setHost(host); // "host" or "host:port" sockudo.setEncrypted(tls); // true -> https sockudo.setRequestTimeout(5000); return sockudo; } } ``` `Sockudo` and `SockudoAsync` implement `AutoCloseable`, so Spring calls `close()` on the bean at shutdown and releases the connection pool. | Option | Type | Default | Description | | --- | --- | --- | --- | | `appId`, `key`, `secret` (constructor) | `String` | required | App credentials. Empty values throw `IllegalArgumentException`. | | `encryptionMasterKeyBase64` (4th constructor argument) | `String` | none | Base64 of a 32-byte key for `private-encrypted-*` channels. | | `setHost` | `String` | `"api.sockudo.io"` | API host. There is no separate port setter; append the port, for example `"127.0.0.1:6001"`. | | `setCluster` | `String` | — | Sets the host to `api-{cluster}.sockudo.io`. For self-hosted Sockudo use `setHost`. | | `setEncrypted` | `boolean` | `false` (`http`) | `true` switches to `https`. Enable it for every non-local deployment. | | `setRequestTimeout` | `int` (ms) | `4000` | Synchronous client only. Applied as connect, socket, and pool-checkout timeout. | | `configureHttpClient` | `HttpClientBuilder` / `DefaultAsyncHttpClientConfig.Builder` | `defaultHttpClientBuilder()` / `Dsl.config()` | Replace the underlying HTTP client: proxy, pool size, TLS, async timeouts. | | `setAutoIdempotencyKey` | `boolean` | `true` | Attach a generated idempotency key to every publish that has none. | | `setDataMarshaller` / `setGsonSerialiser` | `DataMarshaller` / `Gson` | Gson | Controls how event payload objects are serialized. | You can also construct a client from a URL in the form `://:@[:]/apps/`, which sets the scheme, credentials, host, and port at once. The URL contains the secret, so load it from a secret store and never log it: ```java title="SockudoConfig.java" Sockudo sockudo = new Sockudo(System.getenv("SOCKUDO_URL")); // SOCKUDO_URL = "http://APP_KEY:APP_SECRET@127.0.0.1:6001/apps/APP_ID" ``` The client is thread-safe and keeps persistent pooled connections. The default Apache pool allows only 2 concurrent connections per route; for busy services, raise it once at startup instead of creating more clients: ```java title="SockudoConfig.java" PoolingHttpClientConnectionManager pool = new PoolingHttpClientConnectionManager(); pool.setDefaultMaxPerRoute(50); pool.setMaxTotal(50); sockudo.configureHttpClient(Sockudo.defaultHttpClientBuilder().setConnectionManager(pool)); ``` The app secret never leaves your backend. It signs every HTTP API call and every channel auth response, so anyone holding it can publish to any channel, read history, and impersonate any user in presence channels. Keep it in your secret manager or environment, never in client-side code. ### Asynchronous client `SockudoAsync` has the same constructors and methods, but every HTTP call returns `CompletableFuture` instead of `Result`: ```java title="OrderEvents.java" SockudoAsync async = new SockudoAsync(appId, key, secret); async.setHost("127.0.0.1:6001"); CompletableFuture future = async.trigger( "orders", "order.created", Map.of("id", "ord_123"), null, "order.created:tenant-42:ord_123:v1"); future.thenAccept(result -> { if (result.getStatus() != Result.Status.SUCCESS) { scheduleRetry(result); } }); ``` The future completes normally with a `Result` even when the request fails; transport failures surface as `UNKNOWN_ERROR` with a `null` HTTP status rather than as an exceptional completion. Configure timeouts, proxies, and pool limits through `async.configureHttpClient(Dsl.config()...)`. `setRequestTimeout` has no effect on the async client. Async execution is not a durable queue; persist work separately when it must survive a restart. ## Publish an event `trigger` serializes the payload (a `Map` or POJO) to JSON with Gson and returns a `Result`: ```java title="OrderEvents.java" Result result = sockudo.trigger( "orders", "order.created", Map.of("id", "ord_123"), null, // socketId to exclude, or null "order.created:tenant-42:ord_123:v1" // idempotency key, or null ); if (result.getStatus() != Result.Status.SUCCESS) { throw new IllegalStateException( "Sockudo publish failed: " + result.getStatus() + " (HTTP " + result.getHttpStatus() + ")"); } ``` HTTP failures do not throw. Check `getStatus()`; `getHttpStatus()` holds the status code and `getMessage()` the response body on success or an error description on failure. To keep the user who caused an event from receiving their own echo, pass the originating connection's socket ID. The server delivers the event to everyone except that connection, which avoids applying an optimistic UI update twice: ```java title="OrderEvents.java" sockudo.trigger("orders", "order.updated", data, socketIdFromRequest); // e.g. "1302.1081607" ``` ## Publish to many channels or in a batch Pass a list of channels to send the same event to all of them in one request: ```java title="OrderEvents.java" sockudo.trigger( List.of("tenant-42-orders", "user-7-orders"), "order.updated", Map.of("id", "ord_123", "status", "paid"), null, "order.updated:tenant-42:ord_123:v2" ); ``` Pass a `List` to send different events in one request. Each `Event` can carry its own socket ID and idempotency key (`new Event(channel, eventName, data, socketId, idempotencyKey)`), and a sixth `MessageExtras` argument for Protocol V2 extras: ```java title="OrderEvents.java" List batch = List.of( new Event("orders", "order.created", Map.of("id", "ord_124"), null, "order.created:tenant-42:ord_124:v1"), new Event("orders", "order.paid", Map.of("id", "ord_124"), null, "order.paid:tenant-42:ord_124:v1") ); Result result = sockudo.trigger(batch); ``` Client-side checks throw `IllegalArgumentException` before any request is sent: more than 100 channels in one `trigger`, a channel name that does not match `[-a-zA-Z0-9_=@,.;]+`, or a socket ID that is not `digits.digits`. The SDK does not check batch size or name lengths, so the server enforces its `[event_limits]` defaults: `max_channels_at_once = 100`, `max_batch_size = 10`, `max_payload_in_kb = 100`, and `max_name_length = 200`. Exceeding them returns a `Result` with `CLIENT_ERROR` or another non-success status. ## Idempotency and retries A timeout does not tell you whether Sockudo published the event. The request may have been processed and the response lost. Retrying without an idempotency key can deliver the event twice; retrying with the same key lets the server recognize the duplicate. How the server treats keys: - A key can be sent as the `idempotency_key` body field or the `X-Idempotency-Key` header. When both are present the body field wins. The Java SDK sends the same key in both places for `trigger`. - `[idempotency]` defaults are `enabled = true`, `ttl_seconds = 120`, and `max_key_length = 128`. Empty keys are rejected. - A duplicate within the TTL returns the original cached `200` response without publishing again. - For batches, an `X-Idempotency-Key` header identifies the whole batch and each item's `idempotency_key` identifies only that event. The two key spaces do not collide. - If the coordination backend is unavailable the server returns `503 service_unavailable`. A concurrent retry while the first request is still in flight gets `503 backpressure` with `Retry-After: 1`. Retry both with the same key. How this SDK sets keys: - `trigger(channel or channels, event, data, socketId, idempotencyKey)` sends your key. - Batch events carry per-event keys through the `Event` constructor. The SDK has no option for a batch-level `X-Idempotency-Key` header; if you need one, send the request yourself with `post("/batch_events", body, headers)`. - With `setAutoIdempotencyKey(true)` (the default), a publish without a key gets `{baseId}:{serial}` (`{baseId}:{serial}:{index}` for batch events). `baseId` is random per client instance and `serial` increments per call, so these keys deduplicate only the SDK's own retries of that one call. They do **not** protect retries driven by your job queue or a restarted process. - `Sockudo.generateIdempotencyKey()` returns a random 16-character key if you want one to store with a job. A key identifies a logical operation, not an HTTP attempt. Derive it from your domain, for example `order.created:tenant-42:ord_123:v1`, store it with the job, and send the same key on every attempt. Never reuse a key for a different payload. Built-in retries apply to every request and are not configurable: up to 3 attempts in total with 100 ms and 200 ms backoff, resending the identical signed request. | Client | Retried | Not retried | | --- | --- | --- | | `Sockudo` | `SERVER_ERROR` (`5xx`, including `503 backpressure`), `NETWORK_ERROR` (`IOException`) | Every other status, including `429` | | `SockudoAsync` | `SERVER_ERROR` (`5xx`) | Transport failures (`UNKNOWN_ERROR`), `429`, all `4xx` | The backoff does not read `Retry-After`. Handle what remains after the built-in attempts in your own retry policy with the same key. ## Authorize private and presence channels When a client subscribes to a `private-` or `presence-` channel, it asks your backend for a signed auth response. Your endpoint decides whether the signed-in user may join that channel, then asks the SDK to sign. The client sends `socket_id` and `channel_name` form-encoded. ```java title="SockudoAuthController.java" @RestController public class SockudoAuthController { private final Sockudo sockudo; private final UserDirectory users; // your own service public SockudoAuthController(Sockudo sockudo, UserDirectory users) { this.sockudo = sockudo; this.users = users; } @PostMapping( path = "/sockudo/auth", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) public ResponseEntity auth( @RequestParam("socket_id") String socketId, @RequestParam("channel_name") String channelName, Principal principal) { // 1. Authenticate with your own session layer (Spring Security here). if (principal == null) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build(); } AppUser user = users.findByUsername(principal.getName()); // 2. Authorize this user for this exact channel. if (!users.canAccess(user, channelName)) { return ResponseEntity.status(HttpStatus.FORBIDDEN).build(); } try { // 3. Presence identity comes from the session, never from the request. String body = channelName.startsWith("presence-") ? sockudo.authenticate(socketId, channelName, new PresenceUser(user.id(), Map.of("name", user.displayName()))) : sockudo.authenticate(socketId, channelName); return ResponseEntity.ok(body); } catch (IllegalArgumentException invalidRequest) { return ResponseEntity.badRequest().build(); } } } ``` `authenticate` returns the complete JSON body the client expects: `auth`, plus `channel_data` for presence channels and `shared_secret` for encrypted channels. The two-argument form accepts only `private-*` channels and the three-argument form only `presence-*` channels; anything else, or an invalid socket ID or channel name, throws `IllegalArgumentException`. `PresenceUser` takes a `String` or `Number` user ID and any object for `user_info`. The SDK signs whatever you pass it. Check the session and the channel name before calling `authenticate`, and build `PresenceUser` from your server-side user record. If a client could choose its own presence identity, it could impersonate any user in the member list. ### User authentication The Java SDK does not wrap user authentication (signin). If you need it, sign the user object with the public `SignatureUtil.sign` helper, which computes the same HMAC-SHA256 used by the rest of the SDK: ```java title="SockudoAuthController.java" String userData = new Gson().toJson(Map.of("id", user.id(), "user_info", Map.of("name", user.displayName()))); String signature = SignatureUtil.sign(socketId + "::user::" + userData, appSecret); String body = new Gson().toJson(Map.of("auth", appKey + ":" + signature, "user_data", userData)); ``` ### Encrypted channels End-to-end encrypted channels use the `private-encrypted-` prefix. Pass a base64-encoded 32-byte master key (for example from `openssl rand -base64 32`) as the fourth constructor argument: ```java title="SockudoConfig.java" Sockudo sockudo = new Sockudo(appId, key, secret, System.getenv("SOCKUDO_ENCRYPTION_MASTER_KEY")); ``` A key that does not decode to 32 bytes throws `IllegalArgumentException`. With a key configured, `authenticate(socketId, "private-encrypted-...")` adds a per-channel `shared_secret`, and `trigger` encrypts payloads before sending. A single `trigger` call cannot mix an encrypted channel with other channels, and using encrypted channels without a master key throws `SockudoException`. Keep the key in a secret manager and still use TLS. ### Terminate user connections When a user's access changes (logout everywhere, ban, role change), close their sockets: ```java title="AdminService.java" sockudo.terminateUserConnections("user-42"); // Or close with code 4200 so clients reconnect and re-authenticate: sockudo.forceReconnectUser("user-42"); ``` ## Validate webhooks Sockudo signs each webhook body with HMAC-SHA256 using your app secret and sends the result in `X-Pusher-Signature`, with the app key in `X-Pusher-Key`. The signature covers the exact bytes, so validate the raw body before parsing it. Binding the body to a POJO and re-serializing it changes whitespace and key order and breaks the signature. ```java title="SockudoWebhookController.java" @RestController public class SockudoWebhookController { private final Sockudo sockudo; private final WebhookQueue queue; // your own service public SockudoWebhookController(Sockudo sockudo, WebhookQueue queue) { this.sockudo = sockudo; this.queue = queue; } @PostMapping("/sockudo/webhooks") public ResponseEntity receive( @RequestHeader(value = "X-Pusher-Key", required = false) String key, @RequestHeader(value = "X-Pusher-Signature", required = false) String signature, @RequestBody byte[] rawBody) { if (key == null || signature == null) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build(); } String body = new String(rawBody, StandardCharsets.UTF_8); if (sockudo.validateWebhookSignature(key, signature, body) != Validity.VALID) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build(); } Webhook webhook = sockudo.parseWebhook(body); for (WebhookEvent event : webhook.getEvents()) { queue.enqueue(event.getName(), event.getChannel(), event.getRawEvent()); } return ResponseEntity.ok().build(); } } ``` `validateWebhookSignature` returns `VALID`, `INVALID`, or `SIGNED_WITH_WRONG_KEY` (the key header does not match this client's key). Check for missing headers first: passing `null` throws. The parser keeps unknown event names and fields: `WebhookEvent` exposes `getName`, `getChannel`, `getUserId`, `getSocketId`, `getData`, `getRawEvent`, `get(field)`, and serial getters such as `getMessageSerial` and `getVersionSerial`; `Webhook.getTimeMs()` returns the delivery timestamp. There is no built-in key rotation. During a credential rotation, keep a second client built with the previous key and secret and accept the webhook if either client returns `VALID`. Return `200` as soon as the signature checks out and hand events to a queue. Sockudo may retry a delivery, so make processing idempotent. Do not log the raw body or signature. ## Channel state and history Query channel state with the generic signed `get`. Paths are relative to `/apps/{appId}`, and the response JSON is in `getMessage()`: ```java title="ChannelState.java" Result channels = sockudo.get( "/channels", Map.of("filter_by_prefix", "presence-", "info", "user_count")); Result channel = sockudo.get("/channels/presence-lobby", Map.of("info", "user_count")); Result members = sockudo.get("/channels/presence-lobby/users"); if (members.getStatus() == Result.Status.SUCCESS) { String json = members.getMessage(); } ``` Durable history uses `getChannelHistory`. Query parameters are strings: `limit`, `direction`, `cursor`, `start_serial`, `end_serial`, `start_time_ms`, and `end_time_ms`. ```java title="ChannelState.java" Result page = sockudo.getChannelHistory( "orders", Map.of("limit", "50", "direction", "newest_first")); // Read next_cursor from page.getMessage(), then pass it back unchanged: Result next = sockudo.getChannelHistory("orders", Map.of("cursor", nextCursor)); ``` Cursors are opaque: forward `next_cursor` exactly as returned and never build or edit one. Check the response `continuity` block before assuming you have every message. Presence history and snapshots work the same way for presence channels: ```java title="ChannelState.java" Result transitions = sockudo.getChannelPresenceHistory( "presence-lobby", Map.of("limit", "100", "direction", "newest_first")); Result snapshot = sockudo.getChannelPresenceSnapshot( "presence-lobby", Map.of("at_serial", "4")); // or "at_time_ms" ``` ## Versioned messages and annotations These Protocol V2 helpers read and mutate messages by their `message_serial`. Mutation and annotation bodies are JSON strings that follow the server request shape: update accepts fields such as `name`, `data`, `extras`, `description`, `metadata`, `op_id`, `client_id`, and `socket_id`; append requires a string `data`. See [Mutable messages](/docs/server/mutable-messages) for semantics and authorization. ```java title="MessageService.java" Gson gson = new Gson(); String channel = "private-chat-room-1"; Result latest = sockudo.getMessage(channel, messageSerial); Result versions = sockudo.getMessageVersions(channel, messageSerial, Map.of("limit", "20")); sockudo.updateMessage(channel, messageSerial, gson.toJson(Map.of("data", "edited text", "description", "typo fix"))); sockudo.appendMessage(channel, messageSerial, gson.toJson(Map.of("data", " more tokens"))); sockudo.deleteMessage(channel, messageSerial, gson.toJson(Map.of("description", "removed by moderator"))); ``` Annotations attach typed reactions or metadata to a message: ```java title="MessageService.java" Result published = sockudo.publishAnnotation(channel, messageSerial, gson.toJson(Map.of("type", "reactions:distinct.v1", "name", "thumbsup", "clientId", "user-42"))); Result annotations = sockudo.listAnnotations(channel, messageSerial, Map.of("limit", "50")); sockudo.deleteAnnotation(channel, messageSerial, annotationSerial); ``` `listAnnotations` accepts `type`, `from_serial`, `limit`, and `socket_id`; `deleteAnnotation` has an overload that takes query parameters such as `socket_id`. ## Push notifications Push helpers take `Map` bodies, add the `X-Sockudo-Push-Capability` header (`push-admin`, or `push-subscribe` when you pass a device identity token), and return a `Result`. ```java title="PushService.java" sockudo.activateDevice(Map.of( "deviceId", "android-device-1", "clientId", "user-42", "platform", "fcm", "providerToken", "provider-token")); sockudo.upsertChannelPushSubscription(Map.of( "deviceId", "android-device-1", "clientId", "user-42", "channel", "orders")); Result admission = sockudo.publishPush(Map.of( "recipients", List.of(Map.of("type", "channel", "channel", "orders")), "payload", Map.of("title", "Order updated", "body", "Order ord_123 is packed"), "publishId", "push-order-ord_123-packed")); Result status = sockudo.getPublishStatus("push-order-ord_123-packed"); ``` `publishPush` always sets `sync` to `false`. The response is an admission record, not a delivery receipt; poll `getPublishStatus` or consume delivery feedback to learn the provider outcome. Reuse the same `publishId` when you retry a publish. | Area | Methods | | --- | --- | | Devices | `activateDevice` (optional `rotateDeviceIdentityToken` flag), `updateDeviceRegistration`, `listDeviceRegistrations`, `getDeviceRegistration`, `deleteDeviceRegistration`, `removeDeviceRegistrationsByClient` | | Channel subscriptions | `upsertChannelPushSubscription`, `listChannelPushSubscriptions`, `deleteChannelPushSubscriptions`, `listChannelPushSubscriptionChannels` | | Publishing | `publishPush`, `publishPushBatch`, `schedulePush` (requires `notBeforeMs`), `cancelScheduledPush`, `getPublishStatus` | | Provider setup | `listPushCredentials`, `putPushCredential`, `postPushDeliveryStatus` | See [Push notifications](/docs/server/push-notifications) for payload fields and [Push operations](/docs/server/push-operations) for credentials and feedback. For Apple Live Activities, pass the ActivityKit fields as nested maps to `publishPush`, and manage iOS 18 APNs broadcast channels with `createApnsLiveActivityChannel` (storage policy `"noStorage"`, the default, or `"mostRecent"`), `getApnsLiveActivityChannel`, `listApnsLiveActivityChannels`, and `deleteApnsLiveActivityChannel`. See [Apple Live Activities](/docs/server/apple-live-activities) for direct and broadcast payloads and retry semantics. ## Errors and timeouts HTTP and network failures come back as a `Result`, not as exceptions. `Result.Status` classifies them, and `shouldRetry()` reports whether the same request may succeed unchanged: | Status | Cause | `shouldRetry()` | | --- | --- | --- | | `SUCCESS` | `200`, `201`, `202`, `204` | — | | `CLIENT_ERROR` | `400` | false | | `AUTHENTICATION_ERROR` | `401` | false | | `MESSAGE_QUOTA_EXCEEDED` | `403` | false | | `NOT_FOUND` | `404` | false | | `SERVER_ERROR` | `5xx` | true | | `NETWORK_ERROR` | `IOException` in the sync client, including timeouts | true | | `UNKNOWN_ERROR` | Any other status such as `413` or `429`, or an async transport failure | false | Exceptions are reserved for programming and configuration errors: `IllegalArgumentException` for invalid channels, socket IDs, credentials, or keys; `SockudoException` for encrypted-channel misuse; and Gson's `JsonParseException` from `parseWebhook` for a body that is not a JSON object. ```java title="OrderEvents.java" Result result = sockudo.trigger("orders", "order.created", data, null, idempotencyKey); switch (result.getStatus()) { case SUCCESS: break; case SERVER_ERROR: case NETWORK_ERROR: retryQueue.schedule(orderId, idempotencyKey); // same key on every attempt break; default: Integer http = result.getHttpStatus(); if (http != null && http == 429) { retryQueue.scheduleWithBackoff(orderId, idempotencyKey); } else { throw new IllegalStateException("Sockudo rejected publish: HTTP " + http); } } ``` Retry network errors, `429`, and `5xx` with bounded backoff and the original idempotency key. Do not retry `400`, `401`, `403`, or `413`; they need a request or configuration change. Keep `setRequestTimeout` (sync) or the async client's timeouts shorter than the caller's deadline. Never log the app secret, the encryption master key, the client URL, URIs from `signedUri`, event payloads, raw webhook bodies, or provider tokens. Log the status, `getHttpStatus()`, and your own operation ID instead of the full `getMessage()` text. For endpoints without a dedicated helper, `get`, `post(path, body[, headers])`, and `delete(path, params[, headers])` sign requests for paths relative to `/apps/{appId}`. `signedUri(method, path, body[, params])` returns a signed `java.net.URI` for your own HTTP client; its `path` is the full path, such as `/apps/APP_ID/channels`, and the keys `auth_key`, `auth_timestamp`, `auth_version`, `auth_signature`, and `body_md5` are reserved. ## Next steps - [Authentication](/docs/getting-started/authentication): How clients request channel and user auth from your backend. - [HTTP API](/docs/server/http-api): Every endpoint the SDK signs, with request and response shapes. - [Webhooks](/docs/server/webhooks): Webhook events, delivery, and retry behavior. - [Error reference](/docs/reference/errors): Server error codes and what to do about each one.