The Robots Beta API is v0 and the GA API is v1, and each sends its own webhook events. Deploy support for v1 webhook events before you start creating jobs or Directives through /robots/v1. The API version that created a job or Directive determines both its event type and payload. Existing v0 resources continue sending v0 events, including events delivered after your application starts creating v1 resources.

Use Migrate Robots from Beta to GA for request and output mappings, and Migrate Robots Directives from Beta to GA for switching asset creation to v1 Directives.

Accept both event namespaces

Workflow names in event types use underscores: find_key_moments, translate_audio, or generate_engagement_insights. HTTP workflow paths continue using hyphens.

For example, robots.job.translate_audio.completed becomes robots.v1.job.translate_audio.completed. Directive-run events use created, completed, partial, and errored in both namespaces.

Update exact-match handlers, prefix checks, queues, analytics rules, and any event-type allowlists in your own infrastructure. A handler or downstream filter that only accepts robots.job.* will miss robots.v1.job.*.

Keep the existing webhook signature verification, duplicate-delivery handling, and retry behavior. The new namespace does not replace those requirements.

Route payloads by event type

Use the event's type to choose the parser. Don't pick the parser based on which version your app currently creates jobs with: v0 and v1 events arrive side by side during the migration.

The following example dispatches an already verified webhook event. Each handler then parses the payload for its version.

function handleRobotsEvent(event) {
  if (
    event.type.startsWith('robots.v1.job.') ||
    event.type.startsWith('robots.v1.directive_run.')
  ) {
    return handleV1RobotsEvent(event);
  }

  if (
    event.type.startsWith('robots.job.') ||
    event.type.startsWith('robots.directive_run.')
  ) {
    return handleV0RobotsEvent(event);
  }
}

The envelope is unchanged: data is the job or run object itself, in both versions. Do not add an extra job or directive_run wrapper to your parser.

For example, this is an excerpt from a v1 caption-translation event:

{
  "type": "robots.v1.job.translate_captions.completed",
  "data": {
    "id": "rjob_example",
    "workflow": "translate-captions",
    "status": "completed",
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "track_id": "SOURCE_TRACK_ID",
      "output_language_code": "es"
    },
    "outputs": {
      "track_id": "NEW_TRACK_ID",
      "replaced_track_ids": ["DELETED_TRACK_ID"]
    }
  }
}

This excerpt omits unchanged job and event fields. Download URLs remain available where the workflow supplies them. Replacement IDs are optional and appear only when deletions were recorded.

Update job payload parsers

V1 job webhook data uses the same v1 parameter and output field names as a v1 job detail response. Update these together:

• Translation targets use parameters.output_language_code.
• Key-moment duration preferences use parameters.target_duration in seconds.
• Thumbnail times use time; moment and cue intervals use start_time and end_time. Values are seconds and can be fractional.
• Caption editing, caption translation, and audio translation return outputs.track_id.
• Track replacements use replaced_track_ids[] strings instead of replaced_tracks[] objects or singular aliases.
• Premium captions report detected_language_code.
• Chapter asset update outcomes use asset_updates.chapters.
• Deprecated parameters and output aliases are absent.

Use the full response mapping to update each workflow you consume. Keep a v0 parser for old jobs instead of applying v1 renames or unit conversions to every incoming event.

When fetching more details after an event, use /robots/v1/jobs/{workflow}/{JOB_ID} for v1-created jobs and /robots/v0/jobs/{workflow}/{JOB_ID} for v0-created jobs. A wrong-version detail request returns 404.

Update Directive-run payload parsers

V1 events deliver the same run representation used by the v1 start, list, and detail endpoints. For example, a created event has the following type and data:

{
  "type": "robots.v1.directive_run.created",
  "data": {
    "id": "drvrun_example",
    "directive_id": "drv_example",
    "subject_id": "YOUR_ASSET_ID",
    "status": "pending",
    "node_states": [],
    "started_at": 1746403300,
    "completed_at": null
  }
}

V0 Directive-run webhook data uses asset_id; v1 uses subject_id. Nodes use workflow instead of workflow_name. Nodes waiting on another binding report waiting_for_source_bindings and source_bindings[] instead of waiting_for_source_workflow and source_workflows[]. Failure details remain in reason.

The webhook run identifier is data.id in both versions. The run_id → id rename applies to v0 HTTP run responses. See run-response changes for the complete mapping.

Runs started by a Directive, and the jobs they dispatch, send events for the Directive's version. A v0 Directive keeps sending v0 events after you switch your own job requests to v1. Create and attach a v1 Directive to move that Directive's events to v1.

Test before switching to v1

1. Deploy handlers for both versions while you're still creating jobs through v0.
2. Create one v1 job for each workflow your integration uses. Verify event routing, times parsed as seconds, any track IDs, and follow-up GET requests.
3. If you use Directives, start a v1 run and verify both its run event and its child-job events. Check partial and errored handling too.
4. Confirm your consumer still processes a v0 delivery. Retries or outstanding runs can deliver v0 events after the cutover.
5. Switch new requests to v1, and keep monitoring both namespaces.

If you switch new requests back to v0, keep both parsers deployed: jobs and Directives already created through v1 keep sending v1 events. Remove v0 handling only after you've stopped creating v0 jobs, your v0 Directives have stopped running, and remaining deliveries have been accounted for.