---
title: Jobs and events
description: Track accepted work through signed status events.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Jobs and events

A job records work that continues after an HTTP response. Events notify your application when a job, file, or collection changes status.

## Accepted is not complete

*Illustration: An HTTP write returns a job. Engine sends signed status events to your receiver. A recovery read gives the current job state after a missed delivery.*

File ingestion, deletion, reindexing, and some access-rule changes can take time. A `202` response gives you a job ID to retain. The job is the public record of that operation.

| Job status | Meaning |
| --- | --- |
| `queued` | The operation is waiting to start. |
| `running` | The operation is in progress. |
| `succeeded` | The operation completed successfully. |
| `failed` | The operation failed. Read error.code and error.message. |
| `canceled` | The operation stopped after cancellation. |

## Events are the live signal

The operator configures one or more events webhook URLs. Engine sends HTTP POST requests to those receivers. `job.updated`, `file.status_changed`, and `collection.status_changed` describe status transitions.

The event names its cluster and relevant namespace, collection, file, or job. Use those fields to associate the event with your application record. Search, Query, and key changes do not emit these events.

## Handle delivery safely

Check the webhook signature against the raw request body. Reject timestamps more than 300 seconds from your clock. Deduplicate by event `id`; delivery attempts have separate IDs.

Return a `2xx` after your receiver safely accepts the event. Engine retries network failures, `429`, and `5xx`. It does not follow redirects. Each receiver has its own delivery attempts.

## Recover current state

After a missed event, [Get job](/engine/reference/get-job), [Get file](/engine/reference/get-file), or [Get collection](/engine/reference/get-collection) reports the current state. Use these reads for recovery or a one-time check, not repeated live polling.

[Cancel job](/engine/reference/cancel-job) requests cooperative cancellation. Read the returned state and subsequent events. A cancellation request is not a rollback guarantee.

Follow [Handle jobs and events](/engine/guides/jobs-and-events) to configure and verify a receiver. The [webhook contract](/engine/reference/events) lists every header and field.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.