Backend pipeline: AI and your backend, step by step

Some answers need your data. In a backend pipeline, AI steps and your backend take turns: ModelRiver sends a signed webhook when a step needs you, your code replies with just the fields it needs, and the next step continues. Your database never leaves your servers.

How a backend pipeline runs

Example: a customer asks for a refund. AI reads the request, your backend checks the order, AI writes the reply.

  1. Your backend

    Start the run

    Your backend calls POST /v1/ai/async on a workflow with backend steps. You get a channel back right away.

    POST /v1/ai/async
  2. ModelRiver

    First AI step

    The AI reads the request and returns structured output, like the order ID.

    { "order_id": "1234", "intent": "refund" }
  3. Your webhook

    Your backend is called

    A signed webhook (task.ai_generated) brings the AI output and a callback_url.

    POST your-webhook { ai_response, callback_url }
  4. Your backend

    Reply with your data

    Look up the order, apply your rules, then POST only the fields the next step needs to callback_url, within 10 minutes.

    { "data": { "status": "shipped" } }
  5. ModelRiver

    Next AI step

    The next workflow writes the reply using your data. Repeat up to 6 steps in one workflow.

  6. Your users' browser

    See it live

    Progress and the final answer arrive over the WebSocket channel as each step finishes.

    response
webhook.js
// Called when a step needs your data
app.post("/webhook", async (req, res) => {
  res.sendStatus(200); // verify the signature first
  const { ai_response, callback_url } = req.body.data;
  const order = await db.orders.find(ai_response.data.order_id);

  // Reply with only what the next step needs
  await fetch(callback_url, {
    method: "POST",
    headers,
    body: JSON.stringify({ data: { status: order.status } }),
  });
});

When to use a backend pipeline

Use it when

  • The AI needs your private data, like orders, accounts or a CRM record
  • Your business rules decide the outcome, or an action must run on your side
  • The task has several steps: understand, look up, then answer

Pick another pattern when

  • One model call is enough: use Sync or Async
  • You would rather give an agent direct database access: here your backend decides exactly what each step receives

What ModelRiver handles

6 steps

Per workflow

Mix AI steps and backend steps in one run. ModelRiver carries the data from step to step.

10 min

To call back

Your backend has 10 minutes to reply, or the run ends with callback_timeout

Signed

Every webhook

Each call carries x-modelriver-signature (HMAC-SHA256), so you can verify it came from ModelRiver.

Logged

Full timeline

Each AI step, webhook and callback shows up in one timeline in your request logs.

Start from a working backend pipeline