> ## 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.

# Webhook System

> Receive real-time notifications when execution state changes.

## 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:

```json theme={null}
{
  "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](/webhooks/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**

<Warning>
  Your endpoint must respond within 30 seconds with a 2xx status code. Slow responses are treated as failures and trigger retries.
</Warning>

## 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

<CardGroup cols={2}>
  <Card title="Webhook Setup" icon="gear" href="/webhooks/setup">
    Register and manage webhook endpoints.
  </Card>

  <Card title="Signature Verification" icon="shield-check" href="/webhooks/verification">
    Verify HMAC-SHA256 signatures in your language.
  </Card>
</CardGroup>