Docs

Documentation

Monitor your backend's callback responses

For event-driven 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 event-driven 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 event-driven 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 5 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 an event-driven 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 5 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 event-driven workflows
  • Review simulated callbacks to understand the expected flow
  • Verify your handler works with real callbacks using production playground

Next steps