Skip to main content

​
Register an endpoint

Create a webhook endpoint by specifying a URL and the events you want to receive: 
curl -X POST https://api.modelroute.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/modelroute",
    "description": "Production webhook endpoint",
    "events": ["execution.completed", "execution.failed"]
  }'

​
Response

{
  "id": "wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-app.com/webhooks/modelroute",
  "description": "Production webhook endpoint",
  "events": ["execution.completed", "execution.failed"],
  "secret": "whsec_k8m2n4p6r8t0v2x4z6a8c0e2g4i6k8m2n4p6r8t0",
  "is_active": true,
  "created_at": "2026-03-20T10:00:00Z"
}
The secret is only returned once at creation time. Store it securely — you need it to verify webhook signatures.

​
Request body

FieldTypeRequiredDescription
urlstringYesHTTPS URL to receive webhook events
descriptionstringNoHuman-readable label
eventsstring[]NoEvent types to receive. Empty array = all events.
headersobjectNoCustom headers to include in webhook deliveries

​
List endpoints

curl -X GET https://api.modelroute.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_your_api_key_here"

{
  "endpoints": [
    {
      "id": "wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://your-app.com/webhooks/modelroute",
      "events": ["execution.completed", "execution.failed"],
      "is_active": true,
      "failure_count": 0,
      "last_success": "2026-03-20T10:15:00Z"
    }
  ]
}

​
Update an endpoint

curl -X PATCH https://api.modelroute.ai/v1/webhooks/endpoints/wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["execution.completed", "execution.failed", "execution.started"],
    "description": "Updated production webhook"
  }'

​
Delete an endpoint

curl -X DELETE https://api.modelroute.ai/v1/webhooks/endpoints/wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_your_api_key_here"

​
Test an endpoint

Send a test event to verify your endpoint is reachable and correctly processes webhooks: 
curl -X POST https://api.modelroute.ai/v1/webhooks/endpoints/wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890/test \
  -H "Authorization: Bearer sk_your_api_key_here"

​
Response

{
  "success": true,
  "status_code": 200,
  "response_time_ms": 145
}

​
Endpoint health

ModelRoute tracks delivery health per endpoint:
MetricDescription
failure_countConsecutive failed deliveries
last_successTimestamp of last successful delivery
last_failureTimestamp of last failed delivery
last_errorError message from last failure
is_activeWhether the endpoint is active
An endpoint is automatically deactivated after 10 consecutive failures. Reactivate it by updating the endpoint: 
curl -X PATCH https://api.modelroute.ai/v1/webhooks/endpoints/wh_a1b2c3d4.../  \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

​
Event filtering

By default, an endpoint receives all events. Specify an events array to filter: 
{
  "events": ["execution.completed", "execution.failed"]
}
Valid events: execution.started, execution.completed, execution.failed, execution.cancelled.

​
Best practices

Webhook URLs must use HTTPS. HTTP endpoints are rejected.
Return a 2xx status code within 30 seconds. Do heavy processing asynchronously after acknowledging receipt.
Store processed event IDs and skip duplicates. Retries may deliver the same event more than once.
Always verify the HMAC-SHA256 signature before processing. See Webhook Verification.