Webhooks

Use webhooks instead of polling. Pass webhook_url when creating a movie. Keyframe sends lifecycle events as the job progresses.

{
  "type": "movie.completed",
  "movie_id": "movie_abc123",
  "created_at": "2026-06-25T20:15:00Z",
  "data": {
    "status": "completed"
  }
}

Event types

Event	Description
`movie.status_changed`	The movie changed status.
`movie.completed`	The movie completed successfully.
`movie.failed`	The movie failed.
`movie.canceled`	The movie was canceled.

Delivery expectations

Delivery is at least once. Store processed event IDs and make handlers idempotent. Return 2xx to acknowledge receipt. Non-2xx responses may be retried with backoff. Webhook signing details will be documented before public availability.