API Reference
Get a signed HTTPS request the moment a forecast is published, an alert fires, a commission order matches a saved search, or a grid event is recorded. Webhooks are part of the Growth plan.
| Event | Sent when | data |
|---|---|---|
forecast.published | A new price forecast is published | The whole run: market, product, issue time and every block with p10, p50 and p90. |
alert.fired | One of your workspace's alerts fires | The rule, the value that fired it, and when. |
order.matched | A new commission order matches a saved search | The order (authority, docket, date, title, link) and the saved search it matched. |
event.created | A new event is added to the Grid Event Ledger | The event: type, time, state or market, magnitude, headline and its page. |
alert.fired and order.matched go to the workspace whose alert or saved search it is. The other two go to every workspace with an endpoint for them.
Each delivery is a POST with a JSON body: the event's id, type, created_at (UTC) and data.
{
"id": "evt_5c1e0a9f2b7d4e8a6c3f1b0d",
"type": "forecast.published",
"created_at": "2026-10-15T05:02:11.483210+00:00",
"data": {
"run_id": "iex_price_forecast:DAM::2026-10-15T05:00:00+00:00",
"revision": 0,
"market": "DAM",
"product": "d1",
"issued_at": "2026-10-15T05:00:00+00:00",
"delivery_dates": ["2026-10-16"],
"blocks": [
{ "delivery_date": "2026-10-16", "block": 1, "target_ts": "2026-10-15T18:30:00+00:00",
"p10": 3810.2, "p50": 4402.7, "p90": 5120.4 }
]
}
}| Header | Value |
|---|---|
Atlas-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256>; more than one v1 while a secret is rotating |
Atlas-Event-Id | The event's id. The same event delivered twice carries the same id. |
Atlas-Event-Type | One of the four event types above, or webhook.test |
Atlas-Delivery-Id | This delivery to this endpoint |
Atlas-Delivery-Attempt | 1 for the first attempt, then 2 and up for retries |
v1 is the HMAC-SHA256 of <t>.<raw body> under your endpoint's signing secret, in lowercase hex. Check it against the body exactly as received, before you parse it, and refuse a t more than five minutes from your clock.
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 300 # reject deliveries signed more than 5 minutes ago
def verify_atlas_signature(header: str, raw_body: bytes, secret: str, now: float | None = None) -> bool:
"""True when the Atlas-Signature header matches the raw request body."""
timestamp, signatures = None, []
for part in header.split(","):
key, _, value = part.strip().partition("=")
if key == "t" and value.isdigit():
timestamp = int(value)
elif key == "v1" and value:
signatures.append(value)
if timestamp is None or not signatures:
return False
if abs((time.time() if now is None else now) - timestamp) > TOLERANCE_SECONDS:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s) for s in signatures)
# In your handler, verify the body exactly as received, before parsing it:
# ok = verify_atlas_signature(request.headers["Atlas-Signature"], await request.body(), WEBHOOK_SECRET)
Answer with any 2xx within 10 seconds. Anything else, or no answer, is retried after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours and 12 hours. After eight attempts, or 24 hours, the delivery is marked failed; you can send it again from the delivery log.
Atlas-Event-Id to skip one you already handled.Each endpoint has its own signing secret, shown once when you create the endpoint or rotate the secret. After a rotation the old secret keeps signing for 24 hours alongside the new one, so the header carries two v1 values and either verifies. Switch your service to the new secret within the day.
Add, test and remove endpoints, and read every delivery and attempt, under Settings, Webhooks. The same actions are in the API under /v1/webhooks/endpoints and /v1/webhooks/deliveries with your session. A workspace can have ten endpoints.
Test before you rely on it
Send test delivers a webhook.test event at once and shows the response your endpoint gave.