Hubfly spaceDocs
Console

Publish from your server

Your backend publishes events through the server API at https://<host>/apps/<app_id>/…, signed with the app secret exactly like Pusher's HTTP API. Use the Hubfly space server SDK for the Hubfly space extensions, or keep the Pusher library you already have.

Server credentials

A connected project writes these variables for your apps on Hubfly space. Elsewhere, copy them from the Connect page or hubfly realtime env --reveal:

.env
HUBFLY_REALTIME_URL=https://chat-1a2b.rt.hubfly.app
HUBFLY_REALTIME_APP_ID=your-app-id
HUBFLY_REALTIME_KEY=your-app-key
HUBFLY_REALTIME_SECRET=your-app-secret

If you turned on the server API allowlist, the server you publish from must be on it. WebSocket clients are not affected by the allowlist.

Publish with @hubfly/realtime/server

JavaScript
import { RealtimeServer } from "@hubfly/realtime/server";

const realtime = RealtimeServer.fromEnv();

await realtime.channel("orders").publish("order.updated", { id: 42, status: "shipped" });

// Several channels, skipping the connection that caused the change:
await realtime.publish(["orders", "private-user-42"], "order.updated", { id: 42 }, {
  socketId: senderSocketId,
});

fromEnv() reads the HUBFLY_REALTIME_* variables and falls back to PUSHER_APP_ID, PUSHER_APP_KEY, PUSHER_APP_SECRET, PUSHER_HOST, PUSHER_PORT and PUSHER_SCHEME. It runs on Node.js 18+, Bun, Deno and Cloudflare Workers (pass the Worker's env to fromEnv(env)). publish returns the message id and each channel's history position. trigger and triggerBatch are Pusher-compatible equivalents.

Publish with a Pusher server library

Point the library at your server's host on port 443 with TLS and use your Hubfly space app id, key and secret. For example with the Node pusher library:

JavaScript
import Pusher from "pusher";

const pusher = new Pusher({
  appId: process.env.PUSHER_APP_ID,
  key: process.env.PUSHER_APP_KEY,
  secret: process.env.PUSHER_APP_SECRET,
  host: "chat-1a2b.rt.hubfly.app",
  port: "443",
  useTLS: true,
});

await pusher.trigger("orders", "order.updated", { id: 42 });
await pusher.sendToUser("u_42", "notice", { text: "Your export is ready" });

Triggering events (single, multiple channels and batches, with info), channel and presence-user queries, authorizeChannel, authenticateUser, sendToUser, terminateUserConnections and webhook validation behave as with Pusher. Hubfly space tests the Node pusher library and pusher-http-go; other Pusher server libraries that let you set the host use the same signed requests. The Hubfly space endpoints below are also reachable through a Pusher library's generic get and post helpers.

Publish from Go

bash
go get github.com/hubfly/hubfly-sdk/go/realtime
Go
rt, err := realtime.FromEnv()
if err != nil {
	log.Fatal(err)
}

_, err = rt.Publish(ctx, []string{"private-orders"}, "order.created", map[string]int{"id": 42},
	&realtime.PublishOptions{MessageID: "order-42-created"})

_, err = rt.SendToUser(ctx, "u_42", "notification", map[string]string{"title": "Hi"}, nil)

The Go package also provides an auth handler, webhook verification and end-to-end encryption. See the Realtime SDK page.

Direct and user messages

Besides channels, you can send an event straight to one connection or to every connection of a signed-in user. Clients receive them without subscribing to anything.

JavaScript
// connectionId is what the browser got from: const { id } = await realtime.connect()
const result = await realtime.send([connectionId], "export.ready", { url }, { ack: true });

await realtime.toUser("u_42").send("notification", { text: "New message" });

const receipt = await realtime.messageReceipt(result.message_id);
StatusMeaning
deliveredQueued on at least one live connection.
bufferedThe target's session is detached; it gets the message when it resumes.
queuedThe user is offline and the app's offline queue is on; delivered at their next sign-in.
offlineNothing to deliver to; the message is dropped.
acked, expired, droppedReceipt statuses: the client acknowledged it, the buffer or queue time ran out, or the buffer overflowed.
  • Up to 100 targets per send. Receipts are kept for one hour.
  • With ack: true, the Hubfly space client acknowledges after your handler (and the promise it returns) finishes, and the hubfly.message_delivered webhook fires.
  • pusher-js clients receive direct messages through pusher.bind(event), and user messages after signin(). Acknowledgements and session buffering need the Hubfly space client.
  • A user message reaches connections that signed in and joined the user's channel, which pusher-js and the Hubfly space client do automatically after sign-in.

End-to-end connection ids

With end-to-end encryption on, a Hubfly space client's connection id contains a key (<socket_id>~<key>). Treat it as a secret, send it only to your own server, and send to it with the server SDK, which encrypts the message and never passes the key to Hubfly space. See end-to-end encryption.

Message ids and retries

Pass a messageId to publish or send, such as order-42-created. For 5 minutes, repeating a request with the same id for the same app returns the first result and delivers nothing again. Use a new id for every distinct message. Pusher's trigger has no message id, so a retried request can deliver twice.

History, receipts and connections

When an app keeps channel history, you can read it from your server, for example to rebuild state after a client reports recovery:failed:

JavaScript
const { messages, head, truncated } = await realtime.history("orders", { limit: 50 });

const status = await realtime.userStatus("u_42");        // online, connections, socket ids
await realtime.terminate(connectionId, { mode: "disconnect" }); // client reconnects at once
await realtime.terminateUserConnections("u_42");          // closes every connection of the user

terminate with the default mode closes the connection so the client stops reconnecting. channels(), channelInfo(name) and channelUsers(name) list occupied channels, their counts and presence members.

Publish from the terminal

The CLI is handy for tests and scripts. Event data is sent as text:

bash
hubfly realtime publish chat --channel orders --event order.updated --data '{"id":42}'
hubfly realtime send chat --user u_42 --event notice --data-file ./notice.json
hubfly realtime send chat --connection 1234567890.1234567890 --event notice --data hello
hubfly realtime history chat --channel orders --limit 20

Errors and limits

StatusWhen
400Malformed JSON, invalid channel or event names, too many channels (over 100) or events
401Unknown key, bad signature, or a timestamp more than 10 minutes off
403App disabled, the encryption policy requires an encrypted payload, or the caller is not on the server API allowlist
413Payload above the size's or app's message limit
429Over the app's publishes per second; retry after Retry-After seconds
503The server is restarting or busy; retry after Retry-After seconds

Every published or sent event counts toward the publish rate, with a burst of twice the rate. Limits per size are on Sizes, pricing and limits; the full REST contract is in the protocol reference.

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top