Webhooks

Configure HTTPS endpoints in the Developer console to receive signed run lifecycle events. Webhooks complement polling: use them when you need push notification instead of a poll loop.

Subscribable events#

• run.completed: dispatched when a run succeeds.
• run.failed: dispatched when a run fails.
• run.cancelled: dispatched when a run is cancelled.

Verification#

Each delivery includes edgaze-signature: t=<unix>,v1=<hmac> and edgaze-webhook-id. The signed payload is {timestamp}.{raw_json_body} using HMAC-SHA256 with your endpoint secret. Reject signatures older than five minutes to prevent replay.

Verify the signature against the exact bytes received, before parsing or re-serializing the JSON:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyEdgazeWebhook(rawBody, signatureHeader, secret) {
  const fields = Object.fromEntries(
    signatureHeader.split(",").map((field) => {
      const separator = field.indexOf("=");
      return [field.slice(0, separator).trim(), field.slice(separator + 1).trim()];
    }),
  );
  const timestamp = Number(fields.t);
  if (!Number.isFinite(timestamp) || !fields.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${timestamp}.${rawBody}`, "utf8").digest("hex"),
    "hex",
  );
  const actual = Buffer.from(fields.v1, "hex");
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}

In a Next.js Route Handler, obtain rawBody with await request.text() and read the header with request.headers.get("edgaze-signature"). Return a non-2xx response when the header is missing or verification fails.

Delivery guarantees#

• One best-effort attempt per subscribed endpoint, with a five-second timeout.
• There is no retry queue. A non-2xx response, a timeout, or a redirect means the notification is gone; it is not re-sent later.
• Endpoints are called in parallel. Ordering across endpoints is not guaranteed.
• Webhook failures never block run completion: your handler must be idempotent.
• Use test delivery and delivery logs in the Developer console to debug signature or payload issues.
• Return 2xx quickly; defer heavy processing to a background worker using the run id in the payload.

Because a failed delivery is not replayed, treat webhooks as a latency optimization rather than a system of record. If missing a terminal run would cause a correctness or billing problem on your side, reconcile on a schedule with List Runs filtered by status, and use the run id to deduplicate against what you already processed.

A run cancelled through Cancel Run dispatches run.cancelled the same way, and is never charged.

Payload reference#

{
  "type": "run.completed",
  "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "completed",
  "reason": null,
  "runUrl": "https://api.edgaze.ai/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "occurredAt": "2026-07-08T10:00:42.000Z"
}