HTTP Callback

Use the HTTP Callback protocol for GraphQL subscriptions with Hive Router, for router-to-subgraph communication.

HTTP Callback is a subgraph-only protocol. It controls how Hive Router communicates with subgraphs - not how clients connect to the router. Clients always use SSE, Incremental Delivery, Multipart HTTP, or WebSockets.

Subgraphs

Instead of keeping a long-lived connection open to the subgraph, the router registers a subscription with the subgraph over HTTP and provides a callback URL. The subgraph then pushes new events to that URL whenever data is available. This makes HTTP Callback a better fit than WebSockets or HTTP streams when you have many simultaneous open subscriptions, since it avoids the overhead of maintaining persistent connections.

The full protocol is described in the Apollo HTTP Callback Protocol spec.

Configuration

To enable HTTP Callback for subgraphs, configure the subscriptions.callback section and list which subgraphs use this protocol:

subscriptions:
  enabled: true
  callback:
    public_url: https://router.example.com/callback
    subgraphs:
      - reviews
      - products

`public_url`

Required. The URL that subgraphs will POST subscription events to. This must be reachable by your subgraphs - it's the address your router exposes for the subgraphs.

If you're running the router behind a proxy, you might need to set public_url to the external URL that the proxy exposes, and path to the internal path that the router listens on; therefore, the path portion of this URL may or may not match the path option (defaults to /callback).

`path`

The URL path the router listens on for incoming callback messages. Defaults to /callback. Must be absolute, i.e. start with /.

`subgraphs`

The list of subgraph names (as defined in your supergraph schema) that use the HTTP Callback protocol. Subgraphs not listed here fall back to the default protocol negotiation (multipart, then SSE), or WebSockets if websocket is configured, when subscriptions are enabled.

`heartbeat_interval`

How often the subgraph must send a heartbeat to the callback endpoint to keep the subscription alive. Defaults to 5s. Set to 0 to disable heartbeats entirely.

Dedicated Listener

By default, the callback endpoint is registered on the same HTTP server as your main GraphQL endpoint. In production, it's recommended to bind the callback endpoint to a separate port so that subgraph traffic is completely isolated from client traffic.

To do this, set the listen option:

subscriptions:
  enabled: true
  callback:
    public_url: https://router.example.com:4001/callback
    listen: 0.0.0.0:4001
    subgraphs:
      - reviews
      - products

The listen value is an <host>:<port> address. When set, the router starts a dedicated HTTP server on that address exclusively for handling callback messages. Your public_url should reflect the address and port subgraphs will reach.

Using a dedicated listener also lets you put different network policies on the callback port - for example, only allowing traffic from your internal network where subgraphs live, while keeping the main GraphQL port open to the public.

Example

The router starts a dedicated callback server on port 4001, separate from the main GraphQL server. Subgraphs reach it at https://router.internal:4001/callback - an internal address not exposed to public clients. The reviews and products subgraphs use HTTP Callback, while any other subgraphs fall back to the default protocol. Heartbeats are sent every 5 seconds to confirm active subscriptions are still alive.

subscriptions:
  enabled: true
  callback:
    public_url: https://router.internal:4001/callback
    listen: 0.0.0.0:4001
    path: /callback
    heartbeat_interval: 5s
    subgraphs:
      - reviews
      - products

Edit on GitHub

Subgraphs

Configuration

public_url

path

subgraphs

heartbeat_interval