---
title: "workflow_run.awaiting_approval"
method: POST
path: "workflow_run.awaiting_approval"
tags: ["Webhook events"]
---

# workflow_run.awaiting_approval

`POST workflow_run.awaiting_approval` (webhook)

Delivered when a retained workflow result conflicts with newer project edits and needs explicit approval in the project's Tasks drawer. This is not successful application or a generation failure.

## Payload

- WorkflowRunWebhookPayload: Body POSTed when a workflow run completes or its retained result awaits approval. A later successful application has a separate succeeded event. When the run was started with `autoExport: true`, `workflow_run.succeeded` includes `downloadUrl`.
  - `event` 'workflow_run.awaiting_approval' | 'workflow_run.succeeded' | 'workflow_run.failed' | 'workflow_run.cancelled', required: Lifecycle events emitted for workflow runs started via the developer API.
  - `workflowRunId` string, required: Opaque workflow run id matching the original request.
  - `occurredAt` integer, required: Seconds since epoch (Unix timestamp) when this outcome occurred.
  - `workflowType` 'SCRIPT_TO_VIDEO' | 'VOICEOVER_TO_VIDEO' | 'SLIDESHOW_TO_VIDEO' | 'STORYBOARD_TO_VIDEO' | 'PROMPT_TO_VIDEO_CLIP' | 'VIDEO_TO_VIDEO', required: Workflow type identifier.
  - `projectId` string, required: Id of the project created for this workflow run (e.g. `vg_proj_...`).
  - `projectUrl` string, uri, required: Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store `projectId` and use the Projects API (export, remix, metadata). Use `projectUrl` when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard.
  - `error` ApiError: Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details: - `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error. Common `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`.
    - `message` string, required: Human-readable error description. For display and logging only; do not branch on its exact text.
    - `code` string, nullable: Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies.
    - `requirement` ErrorRequirement: What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan).
      - `type` string, required: Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`).
      - `details` object: Key-value pairs with requirement-specific context (e.g. the add-on id to purchase).
    - `internalErrorCode` string, nullable: Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable.
  - `exportId` string, nullable, required: Opaque export id (e.g. `vg_expo_...`) when this run was started with `autoExport: true` and the export succeeded. Always present as a field; `null` otherwise.
  - `downloadUrl` string, uri, nullable, required: Private signed MP4 download URL when `autoExport` succeeded. Always present as a field; `null` otherwise.
  - `downloadUrlExpiresAt` integer, nullable, required: Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` while `downloadUrl` is null.
  - `thumbnailUrl` string, uri, nullable, required: Private signed thumbnail URL when `autoExport` succeeded. Always present as a field; `null` otherwise.
  - `thumbnailUrlExpiresAt` integer, nullable, required: Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` while `thumbnailUrl` is null.
  - `exportFileId` string, nullable, required: File id (e.g. `vg_file_...`) of the rendered MP4 when `autoExport` succeeded. Always present as a field; `null` otherwise.

## Acknowledgement `200`

Acknowledge receipt

---

[API](https://skmtc.dev/videogen/apis/videogen-api.md) - [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/videogen/apis/videogen-api/revisions/25148ccd4132?raw)