Webhook System - ModelRoute

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.started`	Execution dispatched to a provider
`execution.completed`	Execution finished successfully, result available
`execution.failed`	Execution failed with an error
`execution.cancelled`	Execution 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:

Header	Description
`Content-Type`	`application/json`
`X-Signature`	HMAC-SHA256 signature of the payload
`X-Signature-Timestamp`	Unix timestamp used in signature computation
`User-Agent`	`ModelRoute-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

Signature Verification

Verify HMAC-SHA256 signatures in your language.

​Overview

​Events

​Payload format

​Delivery headers

​Signature verification

​Retry policy

​Deduplication

​Next steps

Webhook Setup

Signature Verification

Overview

Events

Payload format

Delivery headers

Signature verification

Retry policy

Deduplication

Next steps