Events, delivery, signatures
Webhooks
Every event the platform emits, and the signature scheme that proves we sent it.
Webhooks turn polling into push. Register an HTTPS endpoint, choose the events you care about, and the platform POSTs a signed JSON payload within seconds of the event. Deliveries retry with exponential backoff for 24 hours; after eight consecutive failures the endpoint is paused and you are emailed.
Event catalog
| event | fires when |
|---|---|
| run.completed | A run reaches completed status; payload includes the result. |
| run.failed | A run halts on error or hits its step ceiling. |
| run.awaiting_approval | An agent run reaches a gated action and pauses. |
| file.processed | An uploaded file finishes extraction into the context graph. |
| fine_tune.succeeded | A training job passes holdout evaluation. |
| fine_tune.failed | A training job failed or regressed against the base. |
| key.near_expiry | A key is 7 days from its scheduled rotation. |
| usage.threshold | Spend crosses a threshold you configured. |
Signature verification
Every delivery carries a Mynd-Signature header: a timestamp and an HMAC-SHA256 of `{timestamp}.{raw_body}` under your endpoint secret. Verify before parsing, and reject timestamps older than five minutes to kill replays.
[ typescript ]ts
import { createHmac, timingSafeEqual } from "crypto";
function verifyWebhook(rawBody: string, header: string, secret: string) {
const [t, sig] = header.split(",").map((p) => p.split("=")[1]);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) {
throw new Error("stale timestamp");
}
const expected = createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
throw new Error("bad signature");
}
return JSON.parse(rawBody);
}Respond 2xx within 10 seconds — do the work async. A 410 response unsubscribes the endpoint permanently.