Server SDKs

Server SDKs are trusted backend libraries. They hold app secrets, sign HTTP requests, sign private and presence channel auth responses, validate webhooks, publish realtime events, and manage push notifications.

Install server SDKs from the package names below. The old per-SDK repositories should be treated as archived/legacy mirrors.

Official SDKs

These packages share the Sockudo/Pusher HTTP signing protocol but differ in their typed helpers. When a new Sockudo endpoint is not yet wrapped by a language SDK, use its generic signed-request helper or generated signed URI rather than implementing HMAC signing independently.

Realtime client or server SDK?

Use a server SDK in a trusted web application, API, worker, or job process. It does not maintain a WebSocket subscription. Use a realtime client in browsers, mobile apps, desktop apps, or backend consumers that need to receive events continuously.

What belongs on the server

• event publishing and batch publishing
• idempotency keys for safe retries
• private, presence, encrypted, and user authentication
• webhook signature validation
• history, versioned messages, annotations, and presence history reads
• push device registration, channel push subscriptions, provider credentials, publish, scheduling, status, and delivery callbacks

Configure one reusable client

Every SDK needs the app ID, public key, secret, HTTP host, port, and TLS mode. Load credentials from a secret manager or environment at process startup, validate them once, and reuse the configured client. Reuse preserves HTTP keep-alive pools and avoids per-request setup overhead.

For a typical deployment:

Do not log connection URLs containing credentials, signed query strings, authorization responses, provider tokens, raw webhooks, or encryption keys.

Publishing model

Use a single publish for one logical event, a multi-channel publish when the same event must reach several channels, and a batch when several independent events can share one HTTP request. Respect the per-SDK and server limits shown in each language guide.

Exclude the originating socket_id when the sender has already applied its own change optimistically. Attach a stable idempotency key derived from the business operation whenever a request may be retried:

order.created:tenant-42:order-123:version-1

An idempotency key identifies a logical operation, not an HTTP attempt. Reusing one key for different payloads can hide a real update.

Authorization endpoints

A correct private or presence authorization handler performs this sequence:

1. Authenticate the application's user session.
2. Validate the socket_id and requested channel_name.
3. Check tenant and resource access for that exact channel.
4. Derive presence user_id and user_info from trusted application data.
5. Ask the server SDK to sign the response.
6. Return only the signed response to the client.

Signing is not authorization by itself. Never implement an endpoint that signs every requested channel, and never accept presence identity directly from the untrusted client.

For private-encrypted-*, configure the SDK's encryption master key and return the derived channel shared secret. Store and rotate the master key like any other high-value application secret.

Webhook handling

Validate the signature against the exact raw request bytes before JSON decoding. Body parsing, whitespace normalization, or character re-encoding can change the signed bytes. Return a non-success response for an invalid signature and avoid logging the raw body.

After validation, enqueue business processing and acknowledge quickly. Webhook handlers should be idempotent because delivery may be retried.

Errors, timeouts, and retries

Retry only transient transport failures, 429, and appropriate 5xx responses. Do not retry validation, authentication, or authorization failures without changing the request. Use exponential backoff with jitter and a bounded attempt count.

Publish retries require an idempotency key. Keep the SDK timeout shorter than the enclosing HTTP request or job deadline so the caller has time to handle the result. Record status code, operation, latency, and retry count without logging credentials or message content.

State, history, and pagination

Application-state endpoints are operational snapshots, not a transactional database. Use them for occupied-channel and presence diagnostics rather than authorization decisions.

History and presence history use bounded pages and opaque cursors. Pass cursors back unchanged; do not parse or construct them. A client performing a gap-free late join should subscribe first and request history through its attach serial.

Push as a backend concern

Client apps may collect device tokens, but server SDKs should register devices and publish push notifications. This keeps app secrets and provider credentials away from browsers and mobile apps.

await sockudo.publishPush({
  recipients: [{ type: "channel", channel: "orders" }],
  payload: {
    title: "Order updated",
    body: "Order ord_123 is packed",
  },
  idempotency_key: "push-order-ord_123-packed",
});

Shared production pattern

1. Instantiate one SDK client per process and reuse it.
2. Use environment variables or secret managers for app credentials.
3. Add idempotency_key to retryable publish and push workflows.
4. Validate private and presence channel access before signing.
5. Validate webhook signatures before parsing business logic.
6. Treat push publish responses as admission records and inspect status asynchronously.
7. Set explicit connect/request timeouts and bounded retries.
8. Monitor request latency, response status, rate limits, and webhook failures.
9. Test credential rotation, duplicate delivery, Sockudo restarts, and network interruption before production rollout.