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, collection, or research run 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 Answer
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
A key registers one or more webhooks. Each webhook has a scope, as a key does: the cluster, namespaces, or collections. Engine sends HTTP POST requests with the events in that scope to the webhook’s URL. job.updated, file.status_changed, and collection.status_changed describe status transitions. file.stage_changed follows an indexing file through its stages. research.updated and research.progress follow a research run. Each POST holds a batch of events.
The event names its cluster and relevant namespace, collection, file, job, or research run. Use those fields to associate the event with your application record. Search, Answer, and key changes do not emit these events.
Handle delivery safely
Verify each POST against the raw request body with a Standard Webhooks library. The library refuses a timestamp more than 5 minutes from your clock. Deduplicate by event id: a retry or a replay can send an event again.
Return a 2xx after your receiver safely accepts the batch. Engine retries network failures, 429, and 5xx until the receiver answers. It does not follow redirects. Each webhook has its own delivery order, and a 30-day delivery log from which you can replay missed events.
Recover current state
After a missed event, Get job, Get file, Get collection, or Get research 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 register and verify a receiver. The webhook contract lists every header and field.