Skip to main content

Send predictions to a webhook

A webhook destination POSTs the latest link SNR forecasts your account's live keys read by link_ids on GET /predictions, and each workflow run whose graph has a destination output naming it, to an HTTPS endpoint you run. Reads by at or as_of_utc, and other model families, are not sent. Every request is signed with a secret only you and Constellation hold, so your endpoint can reject anything that did not come from us.

Webhook destinations come with workflows and need the Operator plan or above; creating one on a lower plan answers 403 plan_required. Send predictions out lists which forecasts a destination receives and how many destinations an account can have.

Connect one​

  1. On Integrations, Results out, choose Add connection, then Webhook.
  2. Enter your endpoint: https:// on a public host name, port 443. IP addresses and private names (.local, .internal) are refused, and so is any host that resolves to a private address when we deliver.
  3. Copy the signing secret shown after you connect. It is shown once and never again; store it where your endpoint can read it.

Constellation sends a check event straight away, and the destination turns Live when your endpoint answers with a 2xx.

To send a workflow's runs there, choose Send in the webhook's detail on Integrations (the workflow you deliver most is already chosen), or tick the webhook under Deliver to in the builder, or add a destination output to the workflow's graph yourself:

{"id": "destination", "kind": "output", "ref": "destination", "params": {"columns": ["expected_gb"], "sort": [], "destination_id": "<the webhook's id>"}}

Saving a graph whose destination output names a destination the account does not have is refused with unknown_destination.

What arrives​

POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: Constellation-Webhooks/1
Constellation-Event: workflow
Constellation-Signature: t=1793919621,v1=5f2c…
Idempotency-Key: run_…:dst_…:0

{"account_id": "acct_…", "workflow": {"slug": "pass-yield", "version": 3, "kind": "pass-yield", "run_id": "run_…"}, "served_at": "2026-11-05T23:00:21.418302+00:00", "items": [ … ]}
Header or fieldMeaning
Constellation-Eventdelivery for served predictions, workflow for a workflow run, check for a connection test
Constellation-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256> of "<t>.<raw body>" with your signing secret
Idempotency-KeyOn delivery and workflow: the same value each time the same message is redelivered. Drop a request whose key you have already handled. A workflow's key is <run_id>:<destination_id>:<part>. Not sent on check.
model_familyon delivery: the model the predictions came from, snr
workflowon workflow: the workflow's slug, the version that ran, what the run answers (kind), and the run
itemsthe results, exactly as GET /predictions (or GET /predictions?run_id=) returns them, with the columns the destination output names

A large workflow run arrives as several workflow requests, each carrying part of its items; the run's workflow.run_id ties them together.

Check the signature​

Recompute the HMAC over the raw body, compare in constant time, and refuse old timestamps:

import hashlib
import hmac
import time


def is_from_constellation(secret: str, header: str, body: bytes, tolerance_s: int = 300) -> bool:
parts = dict(part.split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
if abs(time.time() - timestamp) > tolerance_s:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])

Failures​

Your endpoint answersWhat happens
2xxdelivered; the destination shows when it last delivered
408, 425, 429 or 5xx, or no answer within 10 secondsretried, then set aside after repeated failures
400, 409, 413 or 422that delivery is dropped and not retried; the destination stays active, and its last error names the status
401, 403, 404, 410, any other 4xx, or a 3xxthe destination turns Needs attention with the reason; redirects are never followed. A forecast is not retried, and later ones skip the destination until Send a test passes. A workflow run's delivery is retried, then set aside, and the next run still tries the endpoint

Fix the endpoint, then use Send a test on the destination to check it again.