Webhook event catalog

Fluent event names follow <resource>.<state> where possible. Document lifecycle events add verbs such as created, updated, deleted, and restored for changes that are not document statuses.

​

Document events

Document events apply to documents created from any source, including API runs, email, chat, and schedules.

​

Creation and initial status

Every document insertion emits document.created. If the document is created directly in another subscribed state, Fluent immediately emits the matching status event as well. For example, a quota or intake failure can create a document whose initial status is error. Consumers receive document.created followed by document.error. Both events have previous_status: null. Most documents begin in processing, which has no event of its own, so they initially emit only document.created.

​

Updates

document.updated represents a meaningful human change:

• update.trigger: "user_edit" means a person saved edited document data.
• update.trigger: "rollback" means a person restored an earlier version.

Automated extraction, tools, expressions, and other pipeline writes to document_data do not emit document.updated.

​

Approval outcomes

document.pending_approval, document.approved, and document.rejected describe the approval flow as a whole. They are separate from the per-approver approval.* events. Two transitions are especially important:

• Force approval emits document.approved without requiring preceding approval.approved events for every stage.
• Reopening a rejected document emits document.pending_approval again. Therefore, document.rejected is not necessarily the document’s final event.

​

Processing, trash, and retention

document.processed confirms that Fluent wrote the document to the configured system of record. An agent run can complete before this happens when the document still requires review or approval. document.deleted represents a soft delete. It can be initiated by a person, an API request, or the team’s document-retention policy. Use the included document.status to distinguish an in-flight cancellation from archival of an already processed document. A later restore emits document.restored. Permanent deletion after the trash-retention period does not emit another event.

​

Approval events

Approval events describe one approval unit at one stage. Subscribe to them when your application displays reviewer progress or needs individual votes. If you only need the overall verdict, use the document approval events instead. Each event includes stage_name, stage_position, stage_count, and an approval status. A human vote can include a note. For approval.skipped:

• approver can be null when the approval unit matched nobody.
• note is null.
• reason can explain why the unit was excluded.

Do not leave a skipped unit displayed as awaiting review; it will never receive a vote.

​

API-run events

Run events apply only to runs started through the public agent API. Runs started internally from email, chat, schedules, or other product workflows do not emit run.* events. A run can produce zero, one, or many documents. Terminal run events include the complete document_ids list, which can be empty. A successful text-only run, for example, can emit run.completed without any document event.

​

Events that are not emitted

Fluent does not currently emit events for transient processing or draft document states. These states do not indicate that an external system should act, and omitting them avoids a high-volume stream of intermediate pipeline updates.

​

Forward compatibility

Webhook payloads are additive. Fluent can add fields and event types without changing the webhook version. Consumers should:

• Ignore payload fields they do not recognize.
• Return 2xx for unknown event types after recording them.
• Subscribe to All events only when the consumer safely handles unknown types.

A wildcard subscription receives future event types automatically. A list of individually selected event types does not.