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.
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
| Event | Fields | Fires when |
|---|---|---|
channel_occupied, channel_vacated | channel | The first client subscribes, or the last one leaves. Vacated waits 5 seconds and is skipped if the channel is occupied again. |
member_added, member_removed | channel, user_id | A user's first connection joins a presence channel, or the last one leaves. |
client_event | channel, event, data, socket_id, user_id | Every client event. |
cache_miss | channel | A client subscribes to a cache channel that has no cached event. |
subscription_count | channel, subscription_count | The 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_closed | socket_id, user_id, protocol, code, duration_ms | A connection starts or ends. A resumed session does not open again. |
hubfly.user_online, hubfly.user_offline | user_id | A user's first signed-in connection, or the last session ends. |
hubfly.message_delivered | message_id, socket_id or user_id, status | A 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
{"time_ms":1760600000000,"events":[{"name":"channel_occupied","channel":"orders"}]}| Header | Value |
|---|---|
X-Pusher-Key | The app key the webhook signs with |
X-Pusher-Signature | HMAC-SHA256 (hex) of the raw body with the key's secret, as Pusher sends it |
X-Hubfly space-Signature | t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<body> with the secret |
X-Hubfly space-Delivery-Id | A unique delivery id (wd_…) to deduplicate on |
User-Agent | hubfly-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.
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
httpsonly, 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
localhost. Expose your local receiver with a public HTTPS tunnel, or use Test and the delivery log to check your production endpoint.