Hubfly spaceDocs
Console

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

  1. Create a webhook with an HTTPS URL and the events it should receive.
  2. Verify each request's signature with the app key's secret before trusting it (see the protocol reference).
  3. Send a test delivery, then use the delivery log to find and redeliver failures.

Create a webhook

curl
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.

Open interactive API explorer
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.
  • url must be https:// on port 443 or 8443, at most 2048 characters, with a public host name or public IP and no credentials or fragment.
  • events takes 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 return 400 MANAGED_REALTIME_INVALID_WEBHOOK.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
urlstringYes
eventsstring[]Yes
keyIdstringNo
enabledbooleanNo
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 response
    Response 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 webhookId and status (pending, delivered, failed, dead); other statuses return 400 MANAGED_REALTIME_INVALID_FILTER.
  • limit defaults to 50 (max 100); page with cursor and nextCursor.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
webhookIdqueryNostring—
statusqueryNostring—
limitqueryNonumber—
cursorqueryNostring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
deliveryIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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:admin see the URL's query string replaced with ?[hidden].
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
webhookIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
webhookIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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; keyId must be an active key of the app.
  • A request that changes nothing returns 400 MANAGED_REALTIME_WEBHOOK_UNCHANGED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
webhookIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
urlstringNo
eventsstring[]No
keyIdstringNo
enabledbooleanNo
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 response
    Response 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

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