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:
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-secretIf 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
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:
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
go get github.com/hubfly/hubfly-sdk/go/realtimert, 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.
// 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);| Status | Meaning |
|---|---|
delivered | Queued on at least one live connection. |
buffered | The target's session is detached; it gets the message when it resumes. |
queued | The user is offline and the app's offline queue is on; delivered at their next sign-in. |
offline | Nothing to deliver to; the message is dropped. |
acked, expired, dropped | Receipt 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 thehubfly.message_deliveredwebhook fires. - pusher-js clients receive direct messages through
pusher.bind(event), and user messages aftersignin(). 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
<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:
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 userterminate 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:
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 20Errors and limits
| Status | When |
|---|---|
| 400 | Malformed JSON, invalid channel or event names, too many channels (over 100) or events |
| 401 | Unknown key, bad signature, or a timestamp more than 10 minutes off |
| 403 | App disabled, the encryption policy requires an encrypted payload, or the caller is not on the server API allowlist |
| 413 | Payload above the size's or app's message limit |
| 429 | Over the app's publishes per second; retry after Retry-After seconds |
| 503 | The 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.