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
- On Integrations, Results out, choose Add connection, then Webhook.
- 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. - 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 field | Meaning |
|---|---|
Constellation-Event | delivery for served predictions, workflow for a workflow run, check for a connection test |
Constellation-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> of "<t>.<raw body>" with your signing secret |
Idempotency-Key | On 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_family | on delivery: the model the predictions came from, snr |
workflow | on workflow: the workflow's slug, the version that ran, what the run answers (kind), and the run |
items | the 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 answers | What happens |
|---|---|
| 2xx | delivered; the destination shows when it last delivered |
| 408, 425, 429 or 5xx, or no answer within 10 seconds | retried, then set aside after repeated failures |
| 400, 409, 413 or 422 | that 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 3xx | the 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.