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

# Webhooks

> Receive movie job lifecycle events.

# Webhooks

Use webhooks instead of polling.

Pass `webhook_url` when creating a movie. Keyframe sends lifecycle events as the job progresses.

```json theme={null}
{
  "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.