Webhooks

A webhook pushes results to you instead of making you ask for them. Set an HTTPS endpoint on a flow, and every time a run completes, Tavnit sends that run's extracted rows to your URL as a JSON POST, usually within seconds of the run finishing.

The alternative is polling: calling the API on a timer to ask whether anything finished. Polling costs you requests, adds latency, and gets worse as volume grows. A webhook arrives once, when there is something to deliver.

Flows are the most common source, but most features that produce a result can POST it to a URL. Each one is configured on its own detail page and sends its own payload.

Flow webhooks are configured per flow. You need an HTTPS endpoint that accepts a POST with a JSON body.

1. 1Get an endpoint URL. Automation platforms hand you one when you create a webhook trigger; otherwise expose your own HTTPS route.
2. 2Open the flow in Flows.
3. 3Open the Webhook panel, paste the URL and save.
4. 4Process one test document and confirm the POST arrived. The run's log records whether delivery succeeded and what status code came back.

The body is the run's output plus its identifiers. Repeating line items arrive under rows, single-value fields under metadata, and run_id and flow_id tell you which run produced them.

{
  "run_id": "8f1c2b7e-4d3a-4a91-9c11-2f7b6e0d5a44",
  "flow_id": "3a9d51c0-77b2-4e18-9f6d-0c4a1b8e2d63",
  "rows": [
    {
      "Description": "Software Platform Subscription — January",
      "Quantity": 1,
      "Price": 180.00,
      "Amount": 180.00,
      "Invoice Number": "001",
      "Issued Date": "2026-01-15",
      "Total": 270.30
    }
  ],
  "metadata": {
    "Invoice Number": "001",
    "Billed To": "Acme Ltd",
    "Total": 270.30
  }
}

The field names inside rows and metadata are the ones you defined on the flow, so the payload changes shape when you change the schema. If a Cleaner is attached, what you receive is the cleaned output: converted currencies, computed columns and all. If the Cleaner has a pivot applied to the webhook payload, the rows arrive in the pivoted, wide format.

{
  "run_id": "...",
  "flow_id": "...",

  // present when a Collection routed the document
  "collection_run_id": "b21e9f34-8c55-4d70-a6e2-91f0c7d43a18",

  // present when a Splitter produced this segment
  "split_id": "c74a0b12-3e69-4f85-b0d7-58e2a9c61f70",
  "splitter_doc_title": "Commercial Invoice",

  "rows": [],
  "metadata": {}
}

Every source sends JSON, but the keys differ. Most carry the source's result plus the ids you need to look it up in Tavnit.

{
  "bot_id": "...",
  "bot_run_id": "...",
  "status": "completed",
  "flow_run_id": "...",   // only when a flow run triggered the agent
  "inputs": { "supplier_name": "Acme Ltd" },
  "output": { ... }
}

An agent webhook always includes the agent's input variables (secrets are never included) so your receiver can join the captured output back onto its own records. The flow_run_id tells you which document the agent was working from when a flow run started it.

A conditional action is dispatched as soon as the rule matches, before any review pause. That is deliberate: alert me when this happens should not wait on a reviewer. The flow webhook, by contrast, only fires after a reviewer approves.

In a Pipeline, an Output node sends the results of the nodes feeding it to a destination you pick: Email, Slack, Teams, Google Chat, Webhook, Zapier, Make or n8n.

• Slack, Teams and Google Chat receive a readable message with the key fields, posted through the incoming-webhook URL you paste from that app.
• Webhook, Zapier, Make and n8n receive the raw JSON shown below.
• If a flow in the pipeline already sends its own webhook, the pipeline warns you that an Output would post the same result twice.

{
  "pipeline_id": "...",
  "execution_id": "...",
  "pipeline_name": "Supplier intake",
  "original_filename": "bundle.pdf",
  "outputs": [
    { "node": "Invoice Processor", "node_type": "flow", "output": { ... } }
  ]
}

Every source uses the same delivery rules. Tavnit waits up to 10 seconds for your endpoint to respond. A connection failure or timeout is retried once after a short pause; an HTTP error response is not retried, because your server was reached and answered.

The single most important rule: acknowledge fast, then work. Ten seconds sounds generous until your handler writes to a slow database. Return 200 as soon as you have the payload safely queued, and do the real processing afterwards.

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post("/tavnit-webhook")
def receive():
    payload = request.get_json(silent=True) or {}

    run_id = payload.get("run_id")
    rows = payload.get("rows", [])

    # Acknowledge immediately. Tavnit waits 10 seconds for a response and
    # treats a timeout as a failed delivery, so queue the slow work instead
    # of doing it inline.
    enqueue_processing(run_id, rows)

    return jsonify({"received": True}), 200

import express from "express";

const app = express();
app.use(express.json({ limit: "10mb" }));

app.post("/tavnit-webhook", (req, res) => {
  const { run_id: runId, rows = [] } = req.body ?? {};

  // Respond inside the 10-second window, then do the work.
  res.status(200).json({ received: true });

  enqueueProcessing(runId, rows).catch(console.error);
});

app.listen(3000);

• Accept a reasonably large body: a long invoice with many line items is not small.
• Treat delivery as at-least-once. A retry after a timeout can deliver the same result twice, so make your handler idempotent by keying on run_id (or the source's own id).
• Do not assume a fixed schema. Read fields by name and tolerate ones you do not recognise, so adding a flow field does not break your receiver.
• Log the raw body on failure. It is the only copy of what arrived.

Start at the run, not at your server. Every run logs whether webhook delivery was attempted, whether it succeeded, and what status code or error came back, which immediately tells you whether the problem is Tavnit-side or yours.