Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.modelroute.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
EventTrigger
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

​
Payload format

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"
  }
}

​
Delivery headers

Each webhook request includes these headers:
HeaderDescription
Content-Typeapplication/json
X-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:
AttemptDelay
1st retry2 minutes
2nd retry4 minutes
3rd retry8 minutes
4th retry16 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.