Hubfly spaceDocs
Console

Webhooks

A webhook sends batches of events from one app to an HTTPS endpoint you run, for example to track which channels are occupied or who is online. Webhooks use Pusher's format and signature, so a Pusher library's webhook validator works, and add a timestamped Hubfly space signature against replays.

Add a webhook

Add up to 10 webhooks per app in the server's Webhooks section or with the CLI. Each webhook signs with one of the app's keys.

bash
hubfly realtime webhooks create chat --url https://example.com/hooks/realtime --events channel_occupied,channel_vacated
hubfly realtime webhooks test chat <webhook>      # sends a hubfly.test event
hubfly realtime webhooks deliveries chat --status failed
hubfly realtime webhooks redeliver chat <deliveryId>

People without Realtime admin see webhook URLs with the query string hidden, since receivers often put tokens there.

Events

EventFieldsFires when
channel_occupied, channel_vacatedchannelThe first client subscribes, or the last one leaves. Vacated waits 5 seconds and is skipped if the channel is occupied again.
member_added, member_removedchannel, user_idA user's first connection joins a presence channel, or the last one leaves.
client_eventchannel, event, data, socket_id, user_idEvery client event.
cache_misschannelA client subscribes to a cache channel that has no cached event.
subscription_countchannel, subscription_countThe subscriber count of a non-presence channel changes (at most once per second per channel). Needs Subscription count events in the app settings.
hubfly.connection_opened, hubfly.connection_closedsocket_id, user_id, protocol, code, duration_msA connection starts or ends. A resumed session does not open again.
hubfly.user_online, hubfly.user_offlineuser_idA user's first signed-in connection, or the last session ends.
hubfly.message_deliveredmessage_id, socket_id or user_id, statusA client acknowledged a direct or user message sent with ack.

Clients that come back within 30 seconds of a server restart cause no occupancy, presence or online/offline events.

Payload and headers

JSON
{"time_ms":1760600000000,"events":[{"name":"channel_occupied","channel":"orders"}]}
HeaderValue
X-Pusher-KeyThe app key the webhook signs with
X-Pusher-SignatureHMAC-SHA256 (hex) of the raw body with the key's secret, as Pusher sends it
X-Hubfly space-Signaturet=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<body> with the secret
X-Hubfly space-Delivery-IdA unique delivery id (wd_…) to deduplicate on
User-Agenthubfly-realtime-webhooks/1

With end-to-end encryption, client_event data stays ciphertext; open it on your server with the SDK's decrypt().

Verify signatures

The Hubfly space server SDK checks both signatures and the timestamp (300 seconds of tolerance by default). Verify before you handle events, and pass the raw request: do not parse the body first.

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

const realtime = RealtimeServer.fromEnv();

export async function POST(request: Request) {
  const deliveryId = request.headers.get("X-Hubfly space-Delivery-Id");
  const { events } = await realtime.verifyWebhook(request); // throws WebhookError if invalid
  // Skip deliveryId if you already processed it, then handle events.
  console.log(deliveryId, events);
  return new Response(null, { status: 204 });
}

Pusher libraries' webhook validators (for example pusher.webhook(request).isValid() in Node) accept the X-Pusher-Signature. To check the Hubfly space signature yourself, compute HMAC-SHA256 of t + "." + rawBody with the secret, compare it in constant time with v1, and reject old t values.

Delivery and retries

  • At least once. Events are written to a durable queue on the server together with the change that caused them. Deduplicate on X-Hubfly space-Delivery-Id.
  • Batches and order. Up to 50 events or 256 KiB per request, one request in flight per webhook, in order.
  • Success is any 2xx answer within 10 seconds. Only the first 4 KiB of your response is read and redirects are not followed.
  • Retries back off from 1 second up to 15 minutes, for 24 hours after the batch's oldest event. Then the delivery is marked dead, kept for 7 days and can be redelivered from the Dashboard or with webhooks redeliver. Each attempt is signed with the key's current secret.
  • Backlog. Each webhook queues at most 100,000 events; beyond that events are dropped and counted. Deleting a webhook drops its queue.

Webhook failures appear in the delivery log, in Insights, and as an alert (on by default) when a webhook keeps failing.

Allowed URLs

  • https only, on port 443 or 8443, up to 2,048 characters, without user info or a fragment.
  • Private, loopback, link-local, carrier-grade NAT, multicast, documentation and cloud metadata addresses are refused, after DNS resolution.
  • Apps hosted on Hubfly space can receive webhooks through their public HTTPS address on port 443.

Testing locally

Webhooks cannot reach localhost. Expose your local receiver with a public HTTPS tunnel, or use Test and the delivery log to check your production endpoint.
Something unclear or out of date? Emailsupport@hubfly.spaceBack to top