Webhooks, HMAC Verification & Replay
Build reactive workflows in Slack bots, CI pipelines, billing engines, or SaaS notifications whenever Helix completes work or reaches a human approval gate.
Supported Event Types
| Event Name | Trigger Condition |
|---|---|
run.started | Autonomous sandbox provisioned and execution loop started |
run.completed | Mission reached completed or verified terminal state |
run.failed | Execution aborted or exhausted retries with diagnostic summary |
approval.requested | T2 / T3 gate paused execution waiting on human review |
approval.decided | Reviewer clicked Approve, Rework, or Reject |
ledger.recorded | Ed25519 signed action receipt appended to workspace hash chain |
Step 1 — Register an HTTPS Endpoint
Configure endpoints visually under Developer Console -> Webhooks or programmatically:
curl -X POST https://launchverse.app/api/webhooks/platform \
-H "Authorization: Bearer hx_live_..." \
-H "Content-Type: application/json" \
-d '{
"targetUrl": "https://api.example.com/webhooks/helix",
"events": ["run.completed", "approval.requested", "ledger.recorded"]
}'SSRF guardrails reject plain HTTP,
localhost, loopback (127.0.0.1), link-local (169.254.*), and private RFC1918 CIDRs on public webhooks. For private internal listeners, route via Helix Bridge.
Step 2 — Verify HMAC-SHA256 Signatures (Always!)
Every delivery signs the exact raw UTF-8 request body using your webhook subscription secret (X-Helix-Signature header):
TypeScript / Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyHelixWebhook(rawBody: string, headerSig: string, secret: string): boolean {
const expected = createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
const cleanSig = headerSig.replace(/^sha256=/, "").trim();
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(cleanSig, "utf8");
return a.length === b.length && timingSafeEqual(a, b);
}Python (FastAPI / Flask)
import hmac
import hashlib
def verify_helix_webhook(raw_body: bytes, header_sig: str, secret: str) -> bool:
expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
clean_sig = header_sig.removeprefix("sha256=").strip()
return hmac.compare_digest(expected, clean_sig)Step 3 — Delivery Guarantees & Replay
- Respond with HTTP
2xxwithin 10 seconds to acknowledge delivery; persist heavy jobs asynchronously. - Deduplicate handlers using the unique
deliveryIdin each payload envelope. - Transient failures retry automatically with exponential backoff (
30s -> 2m -> 10m -> 1h). - Replay failed deliveries interactively in Developer Console -> Webhooks or via API:
curl -X POST https://launchverse.app/api/webhooks/platform \
-H "Authorization: Bearer hx_live_..." \
-H "Content-Type: application/json" \
-d '{"action": "replay"}'
