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.
The four patterns
Sync
SimplestYour server sends a request and gets the full AI result back in the same call.
POST /v1/aiSee how it works →Async
Live to usersGet a channel back right away. The result streams to your users and arrives at your webhook.
POST /v1/ai/asyncSee how it works →Backend pipeline
Your data in the loopAI steps and your backend take turns. ModelRiver calls you when a step needs your data.
POST /v1/ai/async + backend stepsAgent
AI calls your APIThe model decides which of your tools to call. Each tool is an endpoint of yours, and ModelRiver makes the signed calls.
POST /v1/ai/async + toolsSee how it works →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.
- Your backend
Start the run
Your backend calls
POST /v1/ai/asyncPOST /v1/ai/asyncon a workflow with backend steps. You get a channel back right away. - ModelRiver
First AI step
The AI reads the request and returns structured output, like the order ID.
{ "order_id": "1234", "intent": "refund" } - Your webhook
Your backend is called
A signed webhook (
POST your-webhook { ai_response, callback_url }task.ai_generated) brings the AI output and acallback_url. - Your backend
Reply with your data
Look up the order, apply your rules, then POST only the fields the next step needs to
{ "data": { "status": "shipped" } }callback_url, within 10 minutes. - ModelRiver
Next AI step
The next workflow writes the reply using your data. Repeat up to 6 steps in one workflow.
- Your users' browser
See it live
Progress and the final answer arrive over the WebSocket channel as each step finishes.
response
// 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
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.