Production AI Webhooks

Webhooks enable your backend to receive real-time notifications when async AI requests complete. Event-driven workflows extend this further, allowing you to process AI-generated data with custom logic before sending the final response to your users.

Why use webhooks?

• Async background processing – Don't keep client connections open; ModelRiver notifies your backend when requests finish
• Reliable delivery – Automatic retries with exponential backoff ensure your backend receives notifications
• Signed payloads – Verify authenticity with HMAC signatures
• Full audit trail – All delivery attempts are logged with timestamps and statuses
• Event-driven workflows – Execute custom business logic between AI generation and final response

Setting up webhooks

1. Create a webhook endpoint in your console

1. Navigate to Webhooks in your project
2. Click Create Webhook
3. Enter your endpoint URL (e.g., https://api.yourapp.com/webhooks/ai)
4. Optionally add a description
5. Save and note the webhook ID

2. Configure your webhook signature secret

ModelRiver signs all webhook payloads so you can verify their authenticity:

1. When creating a webhook, ModelRiver generates a signature secret
2. Store this secret securely in your environment
3. Use it to verify the mr-signature header on incoming requests

Webhook topics

• Standard webhooks: Receive complete AI responses when requests finish
• Event-driven workflows: Process AI output with custom backend logic before final delivery
• Signature verification: Verify webhook authenticity with HMAC-SHA256
• Delivery & retries: Retry policies, monitoring, and dead letter queues

Common patterns

Pattern 1: Fire-and-forget notifications

Standard webhook (no event_name): Receive AI results and trigger side effects (send emails, update databases) without blocking the AI response.

Pattern 2: Tool/function calling workflows

Event-driven workflow with event_name: AI generates a plan, your backend executes tool calls, then you return the final result to the frontend.

Pattern 3: Approval workflows

Event-driven workflow: AI generates content, your backend routes it to an approval queue, human approves, then you call back with the approved content.

Pattern 4: Multi-stage processing

Event-driven workflow: Chain multiple processing steps (AI → validation → enrichment → formatting) before delivering to users.

Next steps

• Review Workflows to understand how to configure event-driven settings
• Check Client SDK for frontend WebSocket integration
• Explore API Integration for async request patterns