Documentation

Monitor your backend's callback responses

For backend pipeline workflows, your backend processes AI responses and calls back to ModelRiver. The timeline tracks callback status, payloads, and timing.

Overview

Backend callbacks are a critical component of backend pipeline workflows. After ModelRiver sends a webhook with the AI response to your backend, your backend processes the data and calls back to ModelRiver via the provided callback_url. The timeline tracks this entire cycle, showing whether your callback was received, timed out, or failed.

How backend callbacks work

The backend pipeline flow

  1. AI generates response → Main request in timeline
  2. Webhook sent to your backend → Webhook delivery in timeline with type: "task.ai_generated" and callback_url
  3. Your backend processes the data → Business logic, database operations, etc.
  4. Your backend calls back → POST to the callback_url with processed data
  5. ModelRiver broadcasts result → Final response sent to WebSocket channels
  6. Callback logged → Backend callback appears in timeline

Seed batch identification

Backend callback log entries have distinctive seed_batch values:

  • "callback:{channel_id}" – Callbacks for production requests
  • "pg_callback:{channel_id}" – Callbacks for playground requests

How backend callbacks appear

In the timeline

  • Position: After webhook deliveries (last item in the timeline)
  • Visual indicator: Lightning bolt icon with "Backend Callback" label
  • Status indicators:
    • Success – Callback received by ModelRiver
    • Timeout – Callback not received within the 5-minute window
    • Simulated – For playground tests, indicates the callback was simulated

When clicked

Clicking a backend callback reveals:

Callback payload

The data your backend received from the webhook delivery. This is the same payload shown in the webhook delivery's Request Data tab:

  • Raw JSON view – Complete webhook payload
  • Preview (tree view) – Interactive JSON tree
  • Copy functionality – Copy for debugging

Callback response

The data your backend sent back to ModelRiver via the callback_url:

  • Raw JSON view – Complete callback response
  • Preview (tree view) – Interactive JSON tree
  • Copy functionality – Copy for analysis

Callback status

Success

What it means: ModelRiver received your backend's callback within the 5-minute window.

What to check:

  • Verify the callback response data is correct
  • Ensure the final response was broadcast to WebSocket channels
  • Confirm the processed data matches expectations

Timeout

What it means: Your backend did not call the callback_url within 10 minutes.

What happens on timeout:

  1. ModelRiver sends a timeout error to WebSocket channels
  2. The timeout event is logged
  3. The request is marked as failed

Common causes:

  • Your backend threw an error during processing
  • Your backend didn't receive the webhook (check webhook delivery status first)
  • Processing took longer than 5 minutes
  • Your backend didn't call the callback_url
  • Network issues prevented the callback from reaching ModelRiver

How to debug:

  1. First check the webhook delivery status: did your backend receive the webhook?
  2. Check your backend logs for processing errors
  3. Verify your backend is making a POST to the correct callback_url
  4. Check if processing time exceeds the 5-minute limit
  5. Verify network connectivity from your backend to ModelRiver

Simulated

What it means: The callback was simulated as part of a playground test. In playground mode, ModelRiver simulates the callback response to show the complete workflow without requiring your actual backend to respond.

When this appears: Only in playground test responses. Production callbacks are never simulated.

Callback payload format

What your backend receives (webhook)

Your webhook handler receives a payload containing:

  • type: "task.ai_generated" – Indicates this is a backend pipeline callback request
  • data – The AI-generated response data
  • callback_url – The URL your backend must call back with processed data
  • channel_id – The unique identifier for this async request

What your backend sends back

Your backend should POST to the callback_url with:

  • The processed data in the request body
  • Any additional fields your application needs in the final response

Debugging callback issues

Callback not appearing in timeline

Possible causes:

  1. Webhook delivery failed: check webhook status first
  2. Your backend didn't call the callback_url
  3. Callback is still in progress (within the 5-minute window)

Callback shows timeout

Step-by-step debugging:

  1. Check webhook delivery – Did your backend receive the webhook?
  2. Check backend logs – Did your backend process the webhook?
  3. Check callback_url – Is your backend calling the correct URL?
  4. Check callback payload – Is your backend sending valid data?
  5. Check timing – Does processing complete within 10 minutes?

Callback succeeded but final response is wrong

Step-by-step debugging:

  1. Review callback response – Open the callback detail and check the response data
  2. Verify processing logic – Is your backend returning the correct processed data?
  3. Check field mapping – Are the response fields in the expected format?
  4. Compare with expectations – Match the callback response against your expected output

Best practices

Keep callbacks fast

  • Process data quickly and call back promptly
  • Move any non-critical processing to after the callback
  • The 5-minute timeout is generous, but faster callbacks mean faster user experience

Handle errors gracefully

  • If your processing fails, call back with an error status
  • Don't let exceptions prevent the callback: use try/catch
  • Log processing errors on your side for debugging

Validate callback data

  • Verify the callback_url is from ModelRiver before processing
  • Validate the AI-generated data before using it
  • Handle missing or unexpected fields gracefully

Test with playground

  • Use playground mode to test backend pipeline workflows
  • Review simulated callbacks to understand the expected flow
  • Verify your handler works with real callbacks using production playground

Next steps