> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.questra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook event types

> Canonical catalog of Program webhook events and their payload schemas. Generated from the storage event registry — do not edit by hand.

Program emits the events below to subscribed webhook endpoints. Payloads use a Standard Webhooks–aligned envelope:

```json theme={null}
{
  "type": "<event_type>",
  "timestamp": "<ISO-8601>",
  "data": { }
}
```

Delivery is **at-least-once**. Use `event.id` (API) / `webhook-id` (header) as your idempotency key and return HTTP 2xx to acknowledge.

This page is generated from `@questra-ai/program-storage` (`repositories/webhooks/events/registry.ts`). Add or change events there, then run `pnpm --filter @questra-ai/program-api generate:openapi`.

## `survey.created`

A survey was created.

### `data` schema (`WebhookEventData_survey_created`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "slug": {
      "type": "string",
      "minLength": 1
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "inspection",
        "programming",
        "reviewing",
        "live",
        "closed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "slug",
    "name",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "survey.created",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "slug": "customer-onboarding",
    "name": "Customer onboarding",
    "description": "Mock survey for onboarding flow experiments.",
    "created_at": "2026-07-01T12:00:00.000Z",
    "updated_at": "2026-07-01T12:00:00.000Z"
  }
}
```

## `survey.updated`

A survey was updated.

### `data` schema (`WebhookEventData_survey_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "slug": {
      "type": "string",
      "minLength": 1
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "inspection",
        "programming",
        "reviewing",
        "live",
        "closed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "slug",
    "name",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "survey.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "slug": "customer-onboarding",
    "name": "Customer onboarding (v2)",
    "description": "Mock survey for onboarding flow experiments.",
    "created_at": "2026-07-01T12:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}
```

## `survey.deleted`

A survey was deleted.

### `data` schema (`WebhookEventData_survey_deleted`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "survey.deleted",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}
```

## `file.created`

A survey file record was created (upload may still be pending).

### `data` schema (`WebhookEventData_file_created`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "survey_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "content_type": {
      "type": "string",
      "minLength": 1
    },
    "size_bytes": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "storage_key": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "ready",
        "failed"
      ]
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ]
    },
    "hosting": {
      "type": "string",
      "enum": [
        "questra",
        "platform"
      ]
    },
    "upstream_path": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "survey_id",
    "name",
    "content_type",
    "size_bytes",
    "storage_key",
    "status",
    "visibility",
    "hosting",
    "upstream_path",
    "content_hash",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "file.created",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000010",
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "name": "stimulus-pack.zip",
    "content_type": "application/zip",
    "size_bytes": null,
    "storage_key": "program/ws_program_seed/surveys/00000000-0000-4000-8000-000000000001/files/00000000-0000-4000-8000-000000000010/stimulus-pack.zip",
    "status": "pending",
    "visibility": "private",
    "hosting": "questra",
    "upstream_path": null,
    "created_at": "2026-07-11T08:00:00.000Z",
    "updated_at": "2026-07-11T08:00:00.000Z"
  }
}
```

## `file.updated`

A survey file record was updated.

### `data` schema (`WebhookEventData_file_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "survey_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "content_type": {
      "type": "string",
      "minLength": 1
    },
    "size_bytes": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "storage_key": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "ready",
        "failed"
      ]
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ]
    },
    "hosting": {
      "type": "string",
      "enum": [
        "questra",
        "platform"
      ]
    },
    "upstream_path": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "survey_id",
    "name",
    "content_type",
    "size_bytes",
    "storage_key",
    "status",
    "visibility",
    "hosting",
    "upstream_path",
    "content_hash",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "file.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000010",
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "name": "stimulus-pack.zip",
    "content_type": "application/zip",
    "size_bytes": 1048576,
    "storage_key": "program/ws_program_seed/surveys/00000000-0000-4000-8000-000000000001/files/00000000-0000-4000-8000-000000000010/stimulus-pack.zip",
    "status": "ready",
    "visibility": "private",
    "hosting": "questra",
    "upstream_path": null,
    "created_at": "2026-07-11T08:00:00.000Z",
    "updated_at": "2026-07-11T09:00:00.000Z"
  }
}
```

## `file.ready`

A survey file finished uploading and is ready to download.

### `data` schema (`WebhookEventData_file_ready`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "survey_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "content_type": {
      "type": "string",
      "minLength": 1
    },
    "size_bytes": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "storage_key": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "ready",
        "failed"
      ]
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ]
    },
    "hosting": {
      "type": "string",
      "enum": [
        "questra",
        "platform"
      ]
    },
    "upstream_path": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "survey_id",
    "name",
    "content_type",
    "size_bytes",
    "storage_key",
    "status",
    "visibility",
    "hosting",
    "upstream_path",
    "content_hash",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "file.ready",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000010",
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "name": "stimulus-pack.zip",
    "content_type": "application/zip",
    "size_bytes": 1048576,
    "storage_key": "program/ws_program_seed/surveys/00000000-0000-4000-8000-000000000001/files/00000000-0000-4000-8000-000000000010/stimulus-pack.zip",
    "status": "ready",
    "visibility": "private",
    "hosting": "questra",
    "upstream_path": null,
    "created_at": "2026-07-11T08:00:00.000Z",
    "updated_at": "2026-07-11T09:00:00.000Z"
  }
}
```

## `file.deleted`

A survey file was deleted.

### `data` schema (`WebhookEventData_file_deleted`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "survey_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id",
    "survey_id"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "file.deleted",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000010",
    "survey_id": "00000000-0000-4000-8000-000000000001"
  }
}
```

## `questionnaire.updated`

A new questionnaire revision was asserted for a survey via PUT .../questionnaire.

### `data` schema (`WebhookEventData_questionnaire_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "survey_id": {
      "type": "string",
      "format": "uuid"
    },
    "revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "survey_id",
    "revision",
    "file_id",
    "created_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "questionnaire.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "revision": 1,
    "file_id": "00000000-0000-4000-8000-000000000010",
    "created_at": "2026-07-13T11:00:00.000Z"
  }
}
```

## `questionnaire.clarifications.updated`

A questionnaire clarifications session changed (inspection started/ready/failed, or answers were submitted).

### `data` schema (`WebhookEventData_questionnaire_clarifications_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "survey_id": {
      "type": "string",
      "format": "uuid"
    },
    "questionnaire_revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "type": "string",
      "enum": [
        "probing",
        "active",
        "complete",
        "failed"
      ]
    },
    "probe_exhausted": {
      "type": "boolean"
    },
    "active_workflow_id": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "clarifications": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "type": "string",
            "enum": [
              "ambiguity",
              "instruction_collision",
              "missing_reference",
              "inconsistency",
              "other"
            ]
          },
          "prompt": {
            "type": "string"
          },
          "context": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                },
                "label": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id",
                "label"
              ],
              "additionalProperties": false
            }
          },
          "response": {
            "anyOf": [
              {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "const": "answer"
                      },
                      "text": {
                        "type": "string",
                        "minLength": 1
                      },
                      "option_id": {
                        "anyOf": [
                          {
                            "type": "string",
                            "minLength": 1
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "required": [
                      "kind",
                      "text",
                      "option_id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "const": "skip"
                      }
                    },
                    "required": [
                      "kind"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "responded_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "resume_path": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "category",
          "prompt",
          "context",
          "options",
          "response",
          "responded_at",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "survey_id",
    "questionnaire_revision",
    "status",
    "probe_exhausted",
    "active_workflow_id",
    "clarifications",
    "summary",
    "error",
    "created_at",
    "updated_at",
    "completed_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "questionnaire.clarifications.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "questionnaire_revision": 1,
    "status": "active",
    "probe_exhausted": true,
    "active_workflow_id": null,
    "clarifications": [
      {
        "id": "50000000-0000-4000-8000-000000000001",
        "category": "ambiguity",
        "prompt": "Q3 asks respondents to “select all that apply” but only lists mutually exclusive brands. Should this be single-select or multi-select?",
        "context": "Question 3 — Brand awareness",
        "options": [
          {
            "id": "opt_single",
            "label": "Treat as single-select"
          },
          {
            "id": "opt_multi",
            "label": "Keep multi-select"
          },
          {
            "id": "opt_rewrite",
            "label": "Rewrite the options to be compatible"
          }
        ],
        "response": {
          "kind": "answer",
          "text": "Treat as single-select",
          "option_id": "opt_single"
        },
        "responded_at": "2026-07-13T11:30:00.000Z",
        "created_at": "2026-07-13T11:15:00.000Z"
      }
    ],
    "summary": null,
    "error": null,
    "created_at": "2026-07-13T11:10:00.000Z",
    "updated_at": "2026-07-13T11:30:00.000Z",
    "completed_at": null
  }
}
```

## `survey.audit.updated`

A survey audit run changed (detect started/completed/failed, or findings were updated).

### `data` schema (`WebhookEventData_survey_audit_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "workspace_id": {
      "type": "string"
    },
    "survey_id": {
      "type": "string",
      "format": "uuid"
    },
    "workflow_id": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "running",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "trigger": {
      "type": "string",
      "enum": [
        "agent",
        "user",
        "programming"
      ]
    },
    "run_number": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "questionnaire_revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "content_revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "platform": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "focus": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "audited_source_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "proposed_source_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "finding_count": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "open_count": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "created_by": {
      "type": "string",
      "minLength": 1
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "workspace_id",
    "survey_id",
    "workflow_id",
    "status",
    "trigger",
    "run_number",
    "questionnaire_revision",
    "content_revision",
    "platform",
    "focus",
    "audited_source_key",
    "proposed_source_key",
    "finding_count",
    "open_count",
    "created_by",
    "error",
    "created_at",
    "updated_at",
    "completed_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "survey.audit.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000021",
    "workspace_id": "ws_program_seed",
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "workflow_id": "wrun_audit_example",
    "status": "completed",
    "trigger": "user",
    "run_number": 1,
    "questionnaire_revision": 1,
    "content_revision": 1,
    "platform": "decipher",
    "focus": null,
    "audited_source_key": "program/ws_program_seed/surveys/00000000-0000-4000-8000-000000000001/audits/00000000-0000-4000-8000-000000000021/audited-source",
    "proposed_source_key": "program/ws_program_seed/surveys/00000000-0000-4000-8000-000000000001/audits/00000000-0000-4000-8000-000000000021/proposed-source",
    "finding_count": 1,
    "open_count": 1,
    "created_by": "60000000-0000-4000-8000-000000000001",
    "error": null,
    "created_at": "2026-08-12T12:00:00.000Z",
    "updated_at": "2026-08-12T12:05:00.000Z",
    "completed_at": "2026-08-12T12:05:00.000Z"
  }
}
```

## `workflow.started`

A workflow was accepted and started (e.g. survey.programming).

### `data` schema (`WebhookEventData_workflow_started`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "kind": {
      "type": "string",
      "enum": [
        "survey.programming",
        "survey.programming.fan_out",
        "survey.questionnaire_clarifications",
        "survey.audit",
        "survey.audit.remediate",
        "survey.migration",
        "survey.simulation",
        "survey.path_walk",
        "survey.behavior_review.regression",
        "survey.behavior_review.replay",
        "fine_tuning_template.populate",
        "workspace.upstream_status_sync"
      ]
    },
    "subject": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "survey",
            "fine_tuning_template",
            "workspace"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "user_id": {
      "type": "string",
      "minLength": 1
    },
    "input": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "output": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "kind",
    "subject",
    "status",
    "user_id",
    "input",
    "output",
    "error",
    "created_at",
    "started_at",
    "updated_at",
    "completed_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "workflow.started",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "40000000-0000-4000-8000-000000000001",
    "kind": "survey.programming",
    "subject": {
      "type": "survey",
      "id": "00000000-0000-4000-8000-000000000001"
    },
    "status": "running",
    "user_id": "60000000-0000-4000-8000-000000000001",
    "input": {
      "survey_id": "00000000-0000-4000-8000-000000000001",
      "file_id": "00000000-0000-4000-8000-000000000010",
      "questionnaire_revision": 1,
      "platform": "decipher",
      "instructions": null,
      "message": null
    },
    "output": null,
    "error": null,
    "created_at": "2026-07-13T12:00:00.000Z",
    "started_at": "2026-07-13T12:00:01.000Z",
    "updated_at": "2026-07-13T12:00:01.000Z",
    "completed_at": null
  }
}
```

## `workflow.updated`

A workflow root status or timing changed while still active (e.g. pending → running).

### `data` schema (`WebhookEventData_workflow_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "kind": {
      "type": "string",
      "enum": [
        "survey.programming",
        "survey.programming.fan_out",
        "survey.questionnaire_clarifications",
        "survey.audit",
        "survey.audit.remediate",
        "survey.migration",
        "survey.simulation",
        "survey.path_walk",
        "survey.behavior_review.regression",
        "survey.behavior_review.replay",
        "fine_tuning_template.populate",
        "workspace.upstream_status_sync"
      ]
    },
    "subject": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "survey",
            "fine_tuning_template",
            "workspace"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "user_id": {
      "type": "string",
      "minLength": 1
    },
    "input": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "output": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "kind",
    "subject",
    "status",
    "user_id",
    "input",
    "output",
    "error",
    "created_at",
    "started_at",
    "updated_at",
    "completed_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "workflow.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "40000000-0000-4000-8000-000000000001",
    "kind": "survey.programming",
    "subject": {
      "type": "survey",
      "id": "00000000-0000-4000-8000-000000000001"
    },
    "status": "running",
    "user_id": "60000000-0000-4000-8000-000000000001",
    "input": {
      "survey_id": "00000000-0000-4000-8000-000000000001",
      "file_id": "00000000-0000-4000-8000-000000000010",
      "questionnaire_revision": 1,
      "platform": "decipher",
      "instructions": null,
      "message": null
    },
    "output": null,
    "error": null,
    "created_at": "2026-07-13T12:00:00.000Z",
    "started_at": "2026-07-13T12:00:01.000Z",
    "updated_at": "2026-07-13T12:05:00.000Z",
    "completed_at": null
  }
}
```

## `workflow.finished`

A workflow reached a terminal state. Read `status` for completed, failed, or cancelled.

### `data` schema (`WebhookEventData_workflow_finished`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "kind": {
      "type": "string",
      "enum": [
        "survey.programming",
        "survey.programming.fan_out",
        "survey.questionnaire_clarifications",
        "survey.audit",
        "survey.audit.remediate",
        "survey.migration",
        "survey.simulation",
        "survey.path_walk",
        "survey.behavior_review.regression",
        "survey.behavior_review.replay",
        "fine_tuning_template.populate",
        "workspace.upstream_status_sync"
      ]
    },
    "subject": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "survey",
            "fine_tuning_template",
            "workspace"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "user_id": {
      "type": "string",
      "minLength": 1
    },
    "input": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "output": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "kind",
    "subject",
    "status",
    "user_id",
    "input",
    "output",
    "error",
    "created_at",
    "started_at",
    "updated_at",
    "completed_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "workflow.finished",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "id": "40000000-0000-4000-8000-000000000001",
    "kind": "survey.programming",
    "subject": {
      "type": "survey",
      "id": "00000000-0000-4000-8000-000000000001"
    },
    "status": "completed",
    "user_id": "60000000-0000-4000-8000-000000000001",
    "input": {
      "survey_id": "00000000-0000-4000-8000-000000000001",
      "file_id": "00000000-0000-4000-8000-000000000010",
      "questionnaire_revision": 1,
      "platform": "decipher",
      "instructions": null,
      "message": null
    },
    "output": {
      "content_revision": 1
    },
    "error": null,
    "created_at": "2026-07-13T12:00:00.000Z",
    "started_at": "2026-07-13T12:00:01.000Z",
    "updated_at": "2026-07-13T12:10:00.000Z",
    "completed_at": "2026-07-13T12:10:00.000Z"
  }
}
```

## `content.updated`

A new survey content revision was created (by programming or CRUD).

### `data` schema (`WebhookEventData_content_updated`)

```json theme={null}
{
  "type": "object",
  "properties": {
    "survey_id": {
      "type": "string",
      "minLength": 1
    },
    "revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "platform": {
      "type": "string",
      "enum": [
        "questra",
        "decipher",
        "confirmit",
        "qualtrics",
        "alchemer"
      ]
    },
    "user_id": {
      "type": "string",
      "minLength": 1
    },
    "message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "change_source": {
      "type": "string",
      "enum": [
        "manual",
        "agent",
        "programming",
        "pull"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "survey_id",
    "revision",
    "platform",
    "user_id",
    "message",
    "change_source",
    "created_at"
  ],
  "additionalProperties": false
}
```

### Example outbound payload

```json theme={null}
{
  "type": "content.updated",
  "timestamp": "2026-07-13T12:00:00.000Z",
  "data": {
    "survey_id": "00000000-0000-4000-8000-000000000001",
    "revision": 1,
    "platform": "decipher",
    "user_id": "60000000-0000-4000-8000-000000000001",
    "message": null,
    "created_at": "2026-07-13T12:10:00.000Z"
  }
}
```