Overview Webhooks let you receive HTTP POST notifications when executions change state. Instead of polling the API, register an endpoint and ModelRoute pushes events to you in real time.
Events ModelRoute sends 4 webhook event types:
Event Trigger execution.startedExecution dispatched to a provider execution.completedExecution finished successfully, result available execution.failedExecution failed with an error execution.cancelledExecution cancelled by user or system
Every webhook delivery is a JSON POST with this structure:
{ "id" : "evt_c3d4e5f6-7890-1234-abcd-ef1234567890" , "event_type" : "execution.completed" , "timestamp" : "2026-03-20T10:32:15Z" , "version" : "1.0" , "organization_id" : "org_a1b2c3d4" , "execution_id" : "exec_b2c3d4e5-f678-9012-abcd-ef1234567890" , "data" : { "id" : "exec_b2c3d4e5-f678-9012-abcd-ef1234567890" , "status" : "COMPLETED" , "model" : "flux-1.1-pro" , "cost" : "0.040" , "latency_ms" : 8420 , "result" : { "file_id" : "file_d4e5f678-9012-3456-abcd-ef1234567890" }, "created_at" : "2026-03-20T10:30:00Z" , "completed_at" : "2026-03-20T10:32:15Z" } }
Each webhook request includes these headers:
Header Description Content-Typeapplication/jsonX-SignatureHMAC-SHA256 signature of the payload X-Signature-TimestampUnix timestamp used in signature computation User-AgentModelRoute-Webhooks/1.0
Signature verification Every webhook is signed with HMAC-SHA256 using your endpoint’s secret. Always verify signatures before processing. See Webhook Verification for implementation details.
Retry policy If your endpoint returns a non-2xx status code or does not respond, ModelRoute retries with exponential backoff:
Attempt Delay 1st retry 2 minutes 2nd retry 4 minutes 3rd retry 8 minutes 4th retry 16 minutes 5th retry (final) 30 minutes (capped)
Maximum 5 retry attempts per delivery
Deliveries expire after 24 hours
After 10 consecutive failures across all deliveries, the endpoint is automatically deactivated
Your endpoint must respond within 30 seconds with a 2xx status code. Slow responses are treated as failures and trigger retries.
Deduplication Each webhook event has a unique id field. If you receive the same event ID twice (due to retries), ignore the duplicate. Store processed event IDs and check before handling.
Next steps
Webhook Setup Register and manage webhook endpoints.
Signature Verification Verify HMAC-SHA256 signatures in your language.
