Webhooks

Send AI results to your backend,signed and retried.

For async requests, ModelRiver posts the result to your webhook URL with an HMAC signature. When a step needs your data, your backend calls back, and ModelRiver carries the result on to the next step or to your users.

Start building freeRead the webhooks docs

How webhooks work

Your app starts the request. Your backend gets the result. Your users see it live.

  1. 01

    Start an async request

    Your app calls POST /v1/ai/async and gets a channel ID back right away, before the model has answered.

  2. 02

    Get a signed delivery

    When the answer is ready, ModelRiver posts it to each webhook URL in your project, signed with your webhook secret.

  3. 03

    Your backend answers

    For a backend pipeline step, your backend reads its own data and posts it to the callback URL within 10 minutes.

  4. 04

    Users see it live

    ModelRiver sends the final result to the WebSocket channel your frontend is listening on.

The numbers

What it looks like

A delivery is a signed JSON envelope. A callback is one authenticated POST.

webhook delivery
POST https://your-app.com/webhooks/modelriver
x-modelriver-signature: 3f9a…c21e
x-modelriver-timestamp: 1793600000
x-modelriver-webhook-id: wh_…

{
  "channel_id": "550e8400-…",
  "timestamp": 1793600000,
  "callback_url": "https://api.modelriver.com/v1/callback/550e8400-…",
  "data": { "status": "success", "data": { … }, "meta": { … } }
}
callback
// Backend pipeline step: add your data, then call back
POST /v1/callback/550e8400-…
Authorization: Bearer mr_live_…

{
  "data": { "order_status": "shipped", "eta": "Nov 6" },
  "task_id": "order_1234"
}

  • Verify every delivery

    Check the HMAC-SHA256 signature with your webhook secret and the timestamp header before you trust a payload.

  • Resend by hand

    Missed one? Resend a delivery from the console or the API within 5 minutes of sending it.

  • Every attempt logged

    Each attempt is stored with its status code, response body, response headers and duration.

Good to know

Frequently asked questions

Which requests send webhooks?

Async requests to /v1/ai/async. Sync requests and the OpenAI-compatible endpoint return the answer in the response and don’t send webhooks.

How do I verify a webhook?

Each delivery has x-modelriver-signature, x-modelriver-timestamp and x-modelriver-webhook-id headers. Check the HMAC-SHA256 signature with your webhook secret, as shown in the signature docs.

What if my endpoint is down?

ModelRiver tries each delivery up to 3 times, waiting longer between tries. You can also resend a delivery by hand within 5 minutes, and every attempt is logged.

What is a backend pipeline?

A workflow of up to 6 steps where your backend adds its own data between AI steps. ModelRiver sends a webhook with a callback URL and waits up to 10 minutes for your backend to post back.

Can I test webhooks on my laptop?

Yes. The ModelRiver CLI forwards webhook deliveries to a local URL, so you can test against localhost.

Wire your backend into an AI workflow

Start on the free plan, add a webhook URL, and send your first async request.

Start building freeRead the webhooks docs