Skip to main content

Webhooks and SDKs

Constellation pushes results to your own HTTPS endpoint as signed webhooks. To call the API, use the Python or TypeScript SDK, the constellation CLI, or any HTTP client.

Webhooks​

A webhook destination POSTs JSON to an endpoint you run: each workflow run whose graph has a destination output naming it, and the latest link SNR forecasts your live keys read by link_ids on GET /predictions. Reads by at or as_of_utc are not sent. Setup, the request and a signature check in Python are in Send forecasts to a webhook.

HeaderCarries
Constellation-Eventworkflow for a run, delivery for served forecasts, check for a connection test
Constellation-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256> of "<t>.<raw body>", keyed with your signing secret
Idempotency-KeyThe same on every delivery of the same request: a run's <run_id>:<destination_id>:<part>, or the delivery's id for served forecasts. A connection test carries none

The body's items are as GET /predictions returns them, in the shared response shape. A large run arrives as several workflow requests, one per part, tied together by workflow.run_id.

To receive them safely:

  1. Check the signature over the raw body, and refuse a timestamp more than a few minutes old.
  2. Drop a request whose Idempotency-Key you have already applied. A delivery that failed is sent again, so the same request can arrive twice.
  3. Answer with a 2xx within 10 seconds.
Your endpoint answersWhat happens
2xxDelivered
408, 425, 429 or 5xx, or nothing within 10 secondsSent again, then set aside after repeated failures
400, 409, 413 or 422Not sent again; the reason is recorded and the destination keeps its status
Any other 4xx, or a redirectNot sent again; the destination shows Needs attention with the reason

Test runs and scenario runs send no webhooks. Webhooks need Operator; see Results out.

Building on Constellation​

WhatIsUse it for
The HTTP APIREST and JSON, with your key in x-api-keyEverything: curl, requests, fetch, any language. Start with the API overview
The SDKsconstellation-space for Python and @constellationspace/client for TypeScript: an API client, a reader of workflow results (constellation_space.results, client.results()) and a base class for bridgesYour own scripts, services and connectors
The constellation CLIOne binary for Linux and macOSLogging in with your key, watching workflow results (constellation results tail), running a mock API, scaffolding and checking a bridge, verifying a download
The fleet agentA Linux service with the constellation-agent command and a local socketPublishing telemetry from your hosts. Its socket protocol takes records only; it reads nothing back
ConnectorsBridges for Yamcs, Open MCT, OpenC3 COSMOS and Anduril Lattice, and a scaffold for your own: Build a connector in Python, TypeScript or Go, checked against a mock APIPutting workflow results in your mission control system (MCS)
The MCP serverTools over the Model Context ProtocolLetting an AI agent read and act on your fleet

The SDKs and the CLI ship with each release of the connectors, on the public connectors GitHub releases, one vX.Y.Z tag for everything. The SDKs are also on PyPI (constellation-space) and npm (@constellationspace/client) from the first public release on. Downloads lists every release file and image, and how to verify and mirror them.

The public contract​

Everything you can build on is published as a contract: the OpenAPI document of every route you call with your own key, the JSON Schema of a workflow result, the telemetry record, and the MCP tools. It is generated from the API's own code and released as a versioned release of the API repository, contract-vX.Y.Z, a tarball with its .sha256. Contract versions follow semantic versioning: a minor version only adds, and a major version removes only what was announced as deprecated. The SDKs are built on it (the TypeScript API types are generated from it, and the Python result types are tested against it), and each connectors release pins the contract version it was built against. Contract and versioning says what stays stable, how deprecations are announced, and which versions work together.

The workflow results endpoints keep their original name, /predictions/feed. The endpoint pages are Telemetry, Topology, Topology config and Predictions.