Realtime API · Dashboard
Webhooks
Send signed channel, presence and connection events to your HTTPS endpoints, and inspect or redeliver deliveries.
Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.
Realtime servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the realtime server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the realtime permissions must hold that exact permission.
How to use these endpoints
- Create a webhook with an HTTPS URL and the events it should receive.
- Verify each request's signature with the app key's secret before trusting it (see the protocol reference).
- Send a test delivery, then use the delivery log to find and redeliver failures.
Create a webhook
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/realtime/apps/$APP_ID/webhooks/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/realtime","events":["channel_occupied","channel_vacated","member_added","member_removed"]}'The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.
Endpoint reference
Dashboard endpoints (7)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
POSTCreate a webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks/create
Add a webhook that receives batches of the chosen events, signed with one of the app's active keys (the newest by default). It is enabled unless enabled is false.
- Requires
realtime:admin. urlmust behttps://on port 443 or 8443, at most 2048 characters, with a public host name or public IP and no credentials or fragment.eventstakes 1–20 of:channel_occupied,channel_vacated,member_added,member_removed,client_event,cache_miss,subscription_count,hubfly.connection_opened,hubfly.connection_closed,hubfly.user_online,hubfly.user_offline,hubfly.message_delivered.- Up to 10 webhooks per app (
409 MANAGED_REALTIME_WEBHOOK_LIMIT); validation errors return400 MANAGED_REALTIME_INVALID_WEBHOOK.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
url | string | Yes |
events | string[] | Yes |
keyId | string | No |
enabled | boolean | No |
Complete request schema
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"keyId": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"url",
"events"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "channel_occupied", "channel_vacated", "member_added", "member_removed", "client_event", "cache_miss", "subscription_count", "hubfly.connection_opened", "hubfly.connection_closed", "hubfly.user_online", "hubfly.user_offline", "hubfly.message_delivered" ] } }, "enabled": { "type": "boolean" }, "keyId": { "type": "string", "nullable": true }, "key": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "appId", "url", "events", "enabled", "keyId", "key", "createdAt", "updatedAt" ], "additionalProperties": false }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true } }, "required": [ "status", "generation", "error" ], "additionalProperties": false } }, "required": [ "webhook", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "webhook": { "id": "string", "appId": "string", "url": "string", "events": [ "channel_occupied" ], "enabled": true, "keyId": "string", "key": "string", "createdAt": "string", "updatedAt": "string" }, "sync": { "status": "pending", "generation": 0, "error": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList webhook deliveriesDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks/deliveries
List the app's webhook delivery log, newest first, with status, attempts, event count, timing, last status code and last error. Deliveries are kept for 7 days.
- Requires
realtime:read. - Filter by
webhookIdandstatus(pending,delivered,failed,dead); other statuses return400 MANAGED_REALTIME_INVALID_FILTER. limitdefaults to 50 (max 100); page withcursorandnextCursor.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
webhookId | query | No | string | — |
status | query | No | string | — |
limit | query | No | number | — |
cursor | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "webhookId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "failed", "delivered", "dead" ] }, "attempts": { "type": "number" }, "events": { "type": "number" }, "firstEvent": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextAttemptAt": { "type": "string", "nullable": true }, "deliveredAt": { "type": "string", "nullable": true }, "lastStatusCode": { "type": "number", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "durationMs": { "type": "number", "nullable": true } }, "required": [ "id", "webhookId", "status", "attempts", "events", "firstEvent", "createdAt", "lastAttemptAt", "nextAttemptAt", "deliveredAt", "lastStatusCode", "lastError", "durationMs" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "webhookId": "string", "status": "pending", "attempts": 0, "events": 0, "firstEvent": "string", "createdAt": "string", "lastAttemptAt": "string", "nextAttemptAt": "string", "deliveredAt": "string", "lastStatusCode": 0, "lastError": "string", "durationMs": 0 } ], "nextCursor": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRedeliver a webhook batchDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks/deliveries/:deliveryId/redeliver
Queue a logged delivery again, including dead or already delivered ones. Returns queued and the deliveryId.
- Requires
realtime:admin. - An unknown delivery ID returns
404 MANAGED_REALTIME_DELIVERY_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
deliveryId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "deliveryId": { "type": "string" } }, "required": [ "queued", "deliveryId" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "queued": true, "deliveryId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList app webhooksDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks
List an app's webhooks with URL, subscribed events, enabled state and the key that signs deliveries. Webhooks are sent with Pusher-compatible X-Pusher-Key and X-Pusher-Signature headers plus X-Hubfly space-Signature and X-Hubfly space-Delivery-Id.
- Requires
realtime:read. - Callers without
realtime:adminsee the URL's query string replaced with?[hidden].
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "channel_occupied", "channel_vacated", "member_added", "member_removed", "client_event", "cache_miss", "subscription_count", "hubfly.connection_opened", "hubfly.connection_closed", "hubfly.user_online", "hubfly.user_offline", "hubfly.message_delivered" ] } }, "enabled": { "type": "boolean" }, "keyId": { "type": "string", "nullable": true }, "key": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "appId", "url", "events", "enabled", "keyId", "key", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "appId": "string", "url": "string", "events": [ "channel_occupied" ], "enabled": true, "keyId": "string", "key": "string", "createdAt": "string", "updatedAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks/:webhookId/delete
Remove a webhook from the app. Its queued, undelivered events are dropped once the server applies the change.
- Requires
realtime:admin.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
webhookId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true } }, "required": [ "status", "generation", "error" ], "additionalProperties": false } }, "required": [ "deleted", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "deleted": true, "sync": { "status": "pending", "generation": 0, "error": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTSend a test webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks/:webhookId/test
Send one signed hubfly.test event to the webhook now and report ok, the receiver's statusCode, durationMs and any error.
- Requires
realtime:admin. - A webhook the server has not applied yet returns
409 MANAGED_REALTIME_SYNC_PENDING; retry shortly. - The server must be running:
409 MANAGED_INSTANCE_NOT_RUNNING.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
webhookId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "statusCode": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true } }, "required": [ "ok", "statusCode", "durationMs", "error" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "ok": true, "statusCode": 0, "durationMs": 0, "error": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTUpdate a webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/webhooks/:webhookId/update
Change a webhook's url, events, signing keyId or enabled state. Omitted fields keep their value.
- Requires
realtime:admin. - Same URL and event rules as creating a webhook;
keyIdmust be an active key of the app. - A request that changes nothing returns
400 MANAGED_REALTIME_WEBHOOK_UNCHANGED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
webhookId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
url | string | No |
events | string[] | No |
keyId | string | No |
enabled | boolean | No |
Complete request schema
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"keyId": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "channel_occupied", "channel_vacated", "member_added", "member_removed", "client_event", "cache_miss", "subscription_count", "hubfly.connection_opened", "hubfly.connection_closed", "hubfly.user_online", "hubfly.user_offline", "hubfly.message_delivered" ] } }, "enabled": { "type": "boolean" }, "keyId": { "type": "string", "nullable": true }, "key": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "appId", "url", "events", "enabled", "keyId", "key", "createdAt", "updatedAt" ], "additionalProperties": false }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true } }, "required": [ "status", "generation", "error" ], "additionalProperties": false } }, "required": [ "webhook", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "webhook": { "id": "string", "appId": "string", "url": "string", "events": [ "channel_occupied" ], "enabled": true, "keyId": "string", "key": "string", "createdAt": "string", "updatedAt": "string" }, "sync": { "status": "pending", "generation": 0, "error": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
Related guides
- Realtime overview and workflows
- Realtime protocol reference (WebSocket, server API and webhooks)
- All Realtime API sections
- Dashboard errors and status codes