Webhook Events

Provide a callback_url when calling Run Agent to receive webhook POSTs for run lifecycle events.

Authentication

If you have a webhook secret configured, every webhook includes an X-Mosaic-Signature header containing the secret as a plaintext string. Validate with a direct comparison:

if request.headers.get('X-Mosaic-Signature') != os.environ['MOSAIC_WEBHOOK_SECRET']:
    return {"error": "Unauthorized"}, 401

Common Fields

Every webhook payload contains these fields:

Field	Type	Description
`flag`	`string`	`"RUN_STARTED"`, `"RUN_PROGRESS"`, or `"RUN_FINISHED"`
`agent_id`	`string`	Agent UUID
`run_id`	`string`	Run UUID
`status`	`string`	Current run status
`node_status_counts`	`object`	`{ completed, in_progress, failed }`
`triggered_by`	`object \| null`	What initiated the run (see below)

RUN_STARTED

Sent when the run begins.

{
  "flag": "RUN_STARTED",
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "status": "running",
  "inputs": [
    {
      "video_url": "https://storage.googleapis.com/.../input.mp4",
      "thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg"
    }
  ],
  "node_status_counts": { "completed": 1, "in_progress": 5, "failed": 0 },
  "triggered_by": null
}

Additional fields: inputs — array of { video_url, thumbnail_url } for the input videos.

RUN_PROGRESS

Sent when one or more nodes change status. Useful for progress tracking without polling.

{
  "flag": "RUN_PROGRESS",
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "status": "running",
  "node_status_counts": { "completed": 4, "in_progress": 3, "failed": 0 },
  "updated_nodes": [
    {
      "original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "status": "completed",
      "status_message": null,
      "outputs": [
        {
          "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "video_url": "https://storage.googleapis.com/...",
          "thumbnail_url": "https://storage.googleapis.com/...",
          "completed_at": "2024-01-15T10:35:00Z",
          "original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8"
        }
      ]
    }
  ],
  "triggered_by": null
}

Additional fields:

Field	Type	Description
`updated_nodes[].original_node_id`	`string \| null`	Template node ID — use to map back to your agent
`updated_nodes[].status`	`string`	`completed`, `running`, `queued`, `failed`, `blocked`, `partial_complete`
`updated_nodes[].status_message`	`string \| null`	Human-readable message
`updated_nodes[].outputs`	`array`	Outputs produced by this node (if any)

RUN_FINISHED

Sent when the run reaches a terminal state. Contains all final outputs.

{
  "flag": "RUN_FINISHED",
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "status": "completed",
  "status_message": null,
  "inputs": [
    {
      "video_url": "https://storage.googleapis.com/.../input.mp4",
      "thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg"
    }
  ],
  "outputs": [
    {
      "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "video_url": "https://storage.googleapis.com/.../output.mp4",
      "thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg",
      "completed_at": "2024-01-15T10:35:00Z",
      "original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8"
    }
  ],
  "node_status_counts": { "completed": 10, "in_progress": 0, "failed": 0 },
  "triggered_by": null
}

Additional fields:

Field	Type	Description
`status`	`string`	`completed`, `partial_complete`, or `failed`
`status_message`	`string \| null`	Human-readable detail on failure
`inputs`	`array`	`{ video_url, thumbnail_url }` for each input
`outputs`	`array`	Final rendered outputs (see below)

Output fields:

Field	Type	Description
`id`	`string`	Render ID — use for chaining runs via `node_render_ids`
`video_url`	`string`	Signed download URL (valid 7 days)
`thumbnail_url`	`string \| null`	Signed thumbnail URL
`completed_at`	`string`	ISO 8601 timestamp
`original_node_id`	`string \| null`	Template node that produced this output

`triggered_by`

Present when the run was started by a trigger or YouTube URL. null for standard API runs.

{
  "type": "youtube",
  "channel_id": "UCxxxxxxxxxxxxxx",
  "video_id": "dQw4w9WgXcQ",
  "video_title": "Never Gonna Give You Up",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "triggered_at": "2024-01-15T10:30:00Z",
  "trigger_id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f"
}

type is one of "youtube", "schedule", or "manual".

Run Status Values

Status	Meaning
`running`	Processing in progress
`completed`	All outputs generated successfully
`partial_complete`	Some outputs succeeded, others failed
`failed`	No outputs generated
`cancelled`	Cancelled by user

Agents

Agent Runs

Agent Nodes

Triggers

Webhooks

Asset Management

Credits

Plan

Social

Authentication

Common Fields

RUN_STARTED

RUN_PROGRESS

RUN_FINISHED

`triggered_by`

Run Status Values

Agents

Agent Runs

Agent Nodes

Triggers

Webhooks

Asset Management

Credits

Plan

Social

​Authentication

​Common Fields

​RUN_STARTED

​RUN_PROGRESS

​RUN_FINISHED

​triggered_by

​Run Status Values

Authentication

Common Fields

RUN_STARTED

RUN_PROGRESS

RUN_FINISHED

`triggered_by`

Run Status Values