Event reference

type WebhookPayload = {
  event:       string;          // event type, e.g. "render.completed"
  timestamp:   string;          // ISO 8601, UTC
  requestId:   string;          // unique delivery ID, matches X-RenderForge-Delivery
  briefId?:    string;          // present for events tied to a brief
  data:        unknown;         // event-specific payload — see below
  metadata?:   Record<string, unknown>; // any metadata you attached to the originating request
};

type RenderCompletedData = {
  status: "completed";
  renderCount: number;
  renders: Array<{
    id: string;                 // render ID
    format: "png" | "jpg" | "webp" | "mp4" | "gif";
    url: string;                // signed download URL, valid for 1h
    width: number;
    height: number;
    bytes: number;
    sha256: string;             // content hash of the rendered bytes
  }>;
};

{
  "event": "render.completed",
  "timestamp": "2026-05-24T18:42:11.812Z",
  "requestId": "evt_2k4j8h9d",
  "briefId": "brief_01HV...",
  "data": {
    "status": "completed",
    "renderCount": 1,
    "renders": [{
      "id": "rnd_01HV...",
      "format": "png",
      "url": "https://cdn.kynva.ai/renders/rnd_01HV.../out.png?sig=...&exp=...",
      "width": 1080,
      "height": 1080,
      "bytes": 184231,
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }]
  },
  "metadata": { "campaign_id": "summer-2026" }
}

type RenderFailedData = {
  status: "failed";
  error: string;                // human message
  code?: string;                // matches an /errors/codes value (e.g. "RENDER_FAILED")
  request_id?: string;          // request_id of the underlying failure
};

{
  "event": "render.failed",
  "timestamp": "2026-05-24T18:43:22.001Z",
  "requestId": "evt_2k4j8h9e",
  "briefId": "brief_01HV...",
  "data": {
    "status": "failed",
    "error": "Font 'AcmeSans' not found in your BrandKit.",
    "code": "RENDER_FAILED",
    "request_id": "req_2k4j8h9f"
  }
}

type CarouselCompletedData = {
  status: "completed";
  carouselId: string;
  slideCount: number;
  zipUrl: string | null;        // if you opted into zip packaging
  slides: Array<{
    index: number;              // 0-based
    renderId: string;
    url: string;
    width: number;
    height: number;
  }>;
};

{
  "event": "carousel.completed",
  "timestamp": "2026-05-24T18:50:11.000Z",
  "requestId": "evt_2k4j8h9g",
  "data": {
    "status": "completed",
    "carouselId": "car_01HV...",
    "slideCount": 5,
    "zipUrl": "https://cdn.kynva.ai/carousels/car_01HV.../slides.zip?sig=...",
    "slides": [
      { "index": 0, "renderId": "rnd_a", "url": "https://...", "width": 1080, "height": 1350 },
      { "index": 1, "renderId": "rnd_b", "url": "https://...", "width": 1080, "height": 1350 }
    ]
  }
}

type CarouselFailedData = {
  status: "failed";
  carouselId: string;
  error: string;
  failedSlideIndexes: number[]; // which slides specifically failed
  partialSlides?: Array<{       // slides that succeeded before the batch failed
    index: number;
    renderId: string;
    url: string;
  }>;
};

type BriefReceivedData = {
  briefId: string;
  source: "api" | "upload" | "email" | "slack";
  receivedAt: string;           // ISO 8601
};

type BatchCompletedData = {
  status: "completed";
  batchId: string;
  totalCount: number;
  successCount: number;
  failureCount: number;
  // Per-brief results — fetch full render details from the render-jobs API.
  results: Array<{
    briefId: string;
    status: "completed" | "failed";
    renderId?: string;
    error?: string;
  }>;
};

curl -X POST https://api.kynva.ai/api/v1/facade/webhooks \
  -H "Authorization: Bearer $KYNVA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://your-app.com/webhooks/kynva",
    "events": [
      "render.completed",
      "render.failed",
      "carousel.completed"
    ]
  }'