Webhooks

Un webhook te envía los resultados en lugar de obligarte a pedirlos. Configura un endpoint HTTPS en un Flow y, cada vez que un Run termina, Tavnit envía las filas extraídas de ese Run a tu URL como un POST con JSON, normalmente pocos segundos después de que el Run termina.

La alternativa es el sondeo: llamar a la API cada cierto tiempo para preguntar si algo terminó. El sondeo consume solicitudes, agrega demora y empeora a medida que crece el volumen. Un webhook llega una sola vez, cuando hay algo que entregar.

Los Flows son el origen más común, pero la mayoría de las funciones que producen un resultado pueden enviarlo por POST a una URL. Cada una se configura en su propia página de detalle y envía su propio payload.

Los webhooks de Flow se configuran por Flow. Necesitas un endpoint HTTPS que acepte un POST con un cuerpo JSON.

1. 1Consigue la URL de un endpoint. Las plataformas de automatización te dan una al crear un disparador de webhook; si no, expón tu propia ruta HTTPS.
2. 2Abre el Flow en Flows.
3. 3Abre el panel Webhook, pega la URL y guarda.
4. 4Procesa un documento de prueba y confirma que llegó el POST. El registro del Run indica si la entrega tuvo éxito y qué código de estado se recibió.

El cuerpo es la salida del Run más sus identificadores. Las partidas repetidas llegan en rows, los campos de valor único en metadata, y run_id y flow_id te dicen qué Run los produjo.

{
  "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
  }
}

Los nombres de campo dentro de rows y metadata son los que definiste en el Flow, así que el payload cambia de forma cuando cambias el esquema. Si hay un Cleaner conectado, recibes la salida limpia: monedas convertidas, columnas calculadas y todo lo demás. Si el Cleaner tiene un pivote aplicado al payload del webhook, las filas llegan en el formato pivotado (ancho).

{
  "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": {}
}

Todos los orígenes envían JSON, pero las claves cambian. La mayoría incluye el resultado del origen más los identificadores que necesitas para encontrarlo en Tavnit.

{
  "bot_id": "...",
  "bot_run_id": "...",
  "status": "completed",
  "flow_run_id": "...",   // solo cuando un Run de Flow disparó al Agente
  "inputs": { "supplier_name": "Acme Ltd" },
  "output": { ... }
}

El webhook de un Agente siempre incluye sus variables de entrada (nunca los secretos) para que tu receptor pueda unir la salida capturada con sus propios registros. El flow_run_id te dice de qué documento partía el Agente cuando lo inició un Run de Flow.

Una acción condicional se envía en cuanto se cumple la regla, antes de cualquier pausa de revisión. Es intencional: avísame cuando pase esto no debería esperar a un revisor. El webhook del Flow, en cambio, solo se dispara después de que un revisor aprueba.

En un Pipeline, un nodo Salida envía los resultados de los nodos que lo alimentan al destino que elijas: Email, Slack, Teams, Google Chat, Webhook, Zapier, Make o n8n.

• Slack, Teams y Google Chat reciben un mensaje legible con los campos clave, publicado mediante la URL de webhook entrante que copias de esa app.
• Webhook, Zapier, Make y n8n reciben el JSON sin procesar que se muestra abajo.
• Si un Flow del Pipeline ya envía su propio webhook, el Pipeline te avisa que una Salida publicaría el mismo resultado dos veces.

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

Todos los orígenes siguen las mismas reglas de entrega. Tavnit espera hasta 10 segundos a que tu endpoint responda. Una falla de conexión o un tiempo agotado se reintenta una vez tras una pausa breve; una respuesta HTTP de error no se reintenta, porque tu servidor fue alcanzado y respondió.

La regla más importante: confirma rápido y después trabaja. Diez segundos parecen suficientes hasta que tu manejador escribe en una base de datos lenta. Responde 200 en cuanto tengas el payload a salvo en una cola y haz el procesamiento real después.

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);

• Acepta cuerpos razonablemente grandes: una factura larga con muchas partidas no es pequeña.
• Trata la entrega como “al menos una vez”. Un reintento después de un tiempo agotado puede entregar el mismo resultado dos veces, así que haz tu manejador idempotente usando run_id (o el identificador propio del origen) como clave.
• No asumas un esquema fijo. Lee los campos por nombre y tolera los que no reconozcas, para que agregar un campo al Flow no rompa tu receptor.
• Registra el cuerpo sin procesar cuando algo falle. Es la única copia de lo que llegó.

Empieza por el Run, no por tu servidor. Cada Run registra si se intentó la entrega del webhook, si tuvo éxito y qué código de estado o error se recibió, lo que te dice de inmediato si el problema está del lado de Tavnit o del tuyo.