Webhook payloads

Fluent sends an HTTPS POST with a JSON body for every delivery attempt.

POST /hooks/fluent HTTP/1.1
Content-Type: application/json
User-Agent: Fluent-Webhooks/1
Fluent-Event-Id: 0c92ee55-2b2a-44ec-bdcc-91c73d48367c
Fluent-Event-Type: document.processed
Fluent-Delivery-Id: 7a517125-0424-48d0-acd0-cf1ca82c8657
Fluent-Attempt: 1
Fluent-Signature: t=1786461631,v1=9c1f...

Request headers

Header	Meaning
`Content-Type`	Always `application/json`.
`User-Agent`	`Fluent-Webhooks/1`.
`Fluent-Event-Id`	Stable event ID and idempotency key. Equal to `body.id`.
`Fluent-Event-Type`	Event name. Equal to `body.type`.
`Fluent-Delivery-Id`	Delivery to this specific endpoint. Stable across its automatic retries.
`Fluent-Attempt`	Current automatic attempt number, beginning at `1`.
`Fluent-Signature`	Timestamped HMAC-SHA256 signature of the raw body.

Use the event ID, not the delivery ID, for business idempotency. The same event can produce distinct delivery IDs when more than one endpoint subscribes.

Common envelope

{
  "id": "0c92ee55-2b2a-44ec-bdcc-91c73d48367c",
  "type": "document.processed",
  "sequence": 4821,
  "created_at": "2026-08-11T15:20:31.123Z",
  "agent_id": "ae8bc83f-d248-484d-909f-49b32e5eac0a",
  "data": {
    "document": {}
  }
}

Field	Type	Meaning
`id`	UUID	Stable event identity. Use it to deduplicate.
`type`	string	Event type from the supported catalog, or a future additive event type.
`sequence`	integer	Global increasing sequence used to reject stale snapshots.
`created_at`	ISO 8601 string	Time Fluent recorded the event.
`agent_id`	UUID	Agent that owns the event.
`data`	object	Event-family data described below.

sequence is globally assigned, so values visible to one team contain gaps. Concurrent transactions can also become visible in a different order from their allocated sequence. Do not use sequence gaps to infer lost events. Use it only to avoid applying an older snapshot over a newer one for the same resource.

Document payload

All document.* and approval.* events include data.document:

{
  "document": {
    "id": "7d20b40d-51be-481d-8f39-808b62084ef7",
    "type": "ap_invoice",
    "status": "processed",
    "previous_status": "approved",
    "run_id": "45e98f7a-31b8-4f26-b760-d8d3ec82df15",
    "conversation_id": "conversation_abc",
    "created_at": "2026-08-11T15:19:02.000Z",
    "processed_at": "2026-08-11T15:20:31.000Z",
    "error": null,
    "url": "https://www.fluenterp.com/w/acme/documents/7d20b40d-..."
  }
}

Field	Meaning
`id`	Durable Fluent document ID.
`type`	Document type reported by the structured data, or `unknown`.
`status`	Document state at event creation time.
`previous_status`	Previous state for status transitions; otherwise `null` or absent.
`run_id`	Public API run that produced the document, or `null`.
`conversation_id`	Source conversation, or `null`.
`created_at`	Document creation time.
`processed_at`	Successful system-of-record processing time, or `null`.
`error`	Current document error, or `null`.
`url`	Fluent product URL for authorized users, or `null` for test data.

The payload does not contain document_data. Fetch the current document with:

curl "https://www.fluenterp.com/api/v1/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $FLUENT_API_KEY"

Document update payload

document.updated adds data.update:

{
  "document": {},
  "update": {
    "version_number": 3,
    "trigger": "user_edit",
    "updated_by": {
      "id": "d38a967b-912d-4ed7-aad0-acde856662ab",
      "name": "Maria Perez"
    }
  }
}

trigger is user_edit or rollback. updated_by can be null, and its name can also be null.

Approval payload

approval.* events add data.approval:

{
  "document": {},
  "approval": {
    "stage_name": "Financial review",
    "stage_position": 1,
    "stage_count": 2,
    "approver": {
      "id": "d38a967b-912d-4ed7-aad0-acde856662ab",
      "name": "Maria Perez",
      "email": "maria@example.com"
    },
    "status": "approved",
    "note": "Amounts verified",
    "reason": null
  }
}

Field	Meaning
`stage_name`	Configured stage label, or `null`.
`stage_position`	Position of this stage in the flow.
`stage_count`	Number of distinct stages currently recorded for the document.
`approver`	Assigned user, or `null` for an unassigned skipped unit.
`status`	`pending`, `approved`, `rejected`, or `skipped`.
`note`	Human approval/rejection note, or `null`.
`reason`	Skip explanation when available; otherwise `null` or absent.

An approval.skipped payload can contain approver: null, note: null, and a non-null reason.

Run payload

run.* events contain data.run instead of a document:

{
  "run": {
    "id": "45e98f7a-31b8-4f26-b760-d8d3ec82df15",
    "status": "completed",
    "error": null,
    "document_ids": [
      "7d20b40d-51be-481d-8f39-808b62084ef7"
    ]
  }
}

document_ids contains every document associated with the API run and can be empty. On run.failed, inspect error; documents produced before the failure still appear in the list.

Correlate runs and documents

Store run_id from POST /api/v1/agents/{agent_id}/run with your source record. Every document created by that API run carries the same ID in data.document.run_id, and the terminal run event lists its document IDs. Do not correlate on extracted values such as supplier, invoice number, or purchase-order number. Those values can change during extraction or review and are not guaranteed unique.

Dispatch events safely

Treat the event name as an open string rather than a closed enum. This keeps your receiver compatible when Fluent adds an event type.

const event = JSON.parse(rawBody) as {
  id: string;
  type: string;
  sequence: number;
  agent_id: string;
  data: Record<string, unknown>;
};

switch (event.type) {
  case "document.processed":
    // Fetch and reconcile the document.
    break;
  default:
    // Record unknown event types and acknowledge them.
    break;
}

Get started

Build with Fluent

Webhooks

Webhook payloads

Request headers

Common envelope

Document payload

Document update payload

Approval payload

Run payload

Correlate runs and documents

Dispatch events safely

​Request headers

​Common envelope

​Document payload

​Document update payload

​Approval payload

​Run payload

​Correlate runs and documents

​Dispatch events safely

Request headers

Common envelope

Document payload

Document update payload

Approval payload

Run payload

Correlate runs and documents

Dispatch events safely