Skip to main content
Webhooks notify your application when an agent’s documents, approvals, or API runs change. They replace continuous polling and cover document changes that can happen after an agent run finishes, such as approval, rejection, and processing into a connected system.

Event catalog

Understand every supported event and its lifecycle semantics.

Payload reference

Review request headers and each payload family.

Delivery and security

Verify signatures and handle retries, ordering, and failures.

Agents

Correlate webhook documents with the run that created them.

​
Configure an endpoint

Only team administrators can manage webhook endpoints.
  1. In Fluent, open Manage, then Agents.
  2. Edit the agent whose events you want to receive.
  3. Open the Access tab and find Webhooks.
  4. Select Add and enter a public HTTPS endpoint URL.
  5. Choose All events or select individual event types.
  6. Save the signing secret in your secret manager when Fluent displays it.
  7. Open the endpoint details and select Send test event.
The signing secret begins with whsec_ and is displayed only once. Fluent stores only an encrypted copy and a short preview. If you lose it, rotate the secret from the endpoint details page.
Your endpoint must use HTTPS, must not contain URL credentials, and must resolve only to public IP addresses. Fluent does not follow redirects.

​
Endpoint scope and subscriptions

Each endpoint belongs to one agent and has its own URL, signing secret, status, and event subscription. An agent can have multiple endpoints with different subscriptions. All events stores the wildcard subscription *. It includes event types added by Fluent in the future. Selecting every event individually is different: it subscribes only to the catalog that existed when you saved the endpoint.
Events are created only when at least one enabled endpoint is subscribed at the time the change occurs. Enabling an endpoint or changing its subscription does not replay earlier events.
Endpoint provisioning is currently managed in the Fluent interface. There is no public /api/v1 endpoint for creating or changing webhook endpoints.

​
Build your receiver

A safe receiver follows this order:
  1. Read the original request body without parsing or re-serializing it.
  2. Verify Fluent-Signature and its timestamp.
  3. Check Fluent-Event-Id against your idempotency store.
  4. Persist the event and the raw body.
  5. Return a 2xx response within 10 seconds.
  6. Process the event asynchronously.
  7. Fetch current document state before an irreversible action.
Webhook payloads are intentionally thin. They identify a document and summarize its state, but they do not include document_data. Use GET /api/v1/documents/{id} when you need the current structured document.

​
Send a test event

The test action sends an ordinary signed document.processed delivery with:
The test has generated event, delivery, and document IDs. It follows the normal signature and retry rules and appears in the delivery log. Check data.test === true before performing business actions.

​
Operate an endpoint

The endpoint details page shows delivery counts, median response time, recent payloads, attempts, response codes, response bodies, and errors. Team administrators can:
  • Enable or disable the endpoint.
  • Change its URL, description, and subscriptions.
  • Send a test event.
  • Manually retry a completed delivery.
  • Rotate the signing secret.
  • Delete the endpoint and its delivery history.
Disabling an endpoint marks its pending deliveries as failed and stops recording new subscribed events for it. Re-enabling resets its consecutive-failure counter, but does not backfill events from the disabled period. Event and delivery history is retained for 30 days.