Jobs and events
AI DraftTrack accepted work through signed status 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
1 · Request
202 Accepted
Retain file.id and job.id.
2 · Event
File ready
Verify the signature and event ID.
3 · Continue
Search or Query
Use the now-ready content.
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 |
|---|---|
| The operation is waiting to start. |
| The operation is in progress. |
| The operation completed successfully. |
| The operation failed. Read error.code and error.message. |
| 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, Get file, or Get collection reports the current state. Use these reads for recovery or a one-time check, not repeated live polling.
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 to configure and verify a receiver. The webhook contract lists every header and field.