Webhooks

HMAC-signed POSTs to your URL when async jobs finish or budget caps fire.

Two paths

Per-request webhook: supply webhook: {url, secret} in any async /v1/* body. Genie POSTs the full job-result body when the job hits a terminal state.
Application alert webhook: set alertWebhookUrl + alertWebhookSecret on an Application via PATCH. Genie POSTs cap-hit + near-cap notifications.

Signature

Every webhook carries:

http
POST {your-url}
Content-Type: application/json
X-Genie-Signature: sha256={hex}
X-Genie-Event: {event-name}
X-Genie-Delivery: {uuid}

{ ...body... }

sha256 is HMAC-SHA256 over the raw body bytes using the secret you supplied. Verify on receipt:

typescript
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Retry policy

Up to 3 attempts on non-2xx response or network error.
Exponential backoff: 5s → 30s → 5min.
After exhaustion, the delivery is marked failed in NotificationLog; no further retries.

Job-completion body shape

json
{
  "id": "vidgen-cmoz...",
  "status": "completed",
  "result": {
    "url": "https://blob.genie.tech/.../video.mp4",
    "durationMs": 12450
  },
  "completedAt": "2026-05-10T08:00:00.000Z"
}