> ## Documentation Index
> Fetch the complete documentation index at: https://docs.immitranslate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

```bash theme={null}
POST https://example-webhook-url.test/webhooks/immitranslate
```

The structure of the POST request:

```json theme={null}
{
  "type": "quote",
  "event": "status_update",
  "target": "quote_a1s2d3f4q5w6e7r8t9y0",
  "data": {
    "token": "quote_a1s2d3f4q5w6e7r8t9y0",
    "status": "ready"
  },
  "url": "https://immitranslate.com/api/v1/quotes/quote_a1s2d3f4q5w6e7r8t9y0"
}
```

Webhooks notify your systems about quote and order lifecycle events, most notably status updates for quotes and orders.

Webhook destinations can be configured in two ways:

* **Account-level** — An account-wide webhook URL receives events for every quote and order within your account. To set your account webhook URL, [go to your Account Settings page](https://immitranslate.com/account/settings/webhook).
* **Quote-level** — An optional `webhook` parameter may be provided when [creating a quote](/quotes#create-quote). This URL receives events for that quote and any resulting order. This is useful for platforms that require per-transaction webhook destinations without configuring an account-wide URL.
* **App-level** — An [OAuth app](/oauth-apps)'s webhook URL receives events for the quotes the app creates and their orders, while the account stays connected, plus `connection` events. These deliveries are signed. See [Webhooks for apps](/oauth-apps#webhooks-for-apps).

If both an account-level and a quote-level webhook URL are configured, each event is delivered to **both** URLs. If both are set to the same URL, only a single request is sent.

Webhook deliveries are sent as HTTP `POST` requests with a JSON body and include the following headers: `Webhook-Id` (a unique identifier for the delivery), `Webhook-Version`, and `Webhook-Account` (your account token). If your endpoint does not respond with a `2xx` status code, delivery is retried up to 3 times with exponential backoff.

## Event Object

| Field | Type | Description |
| - | - | - |
| `type` | String | `quote` or `order`, or `connection` for [OAuth apps](/oauth-apps#webhooks-for-apps). Additional types may be added later. |
| `event` | String | The event that occurred: `status_update`, `created`, `file_created`, or `file_deleted`. See [Event Types](#event-types) for the complete list of events. |
| `target` | String | The unique token for the object associated with the event |
| `data` | Object | Select properties from the target object which can be used to identify the change |
| `url` | String | The unique URL of the object which can be fetched with the API |

## Event Types

The complete list of webhook events is below. For `status_update` events, the `data.status` property contains the new status of the object. Every `order` event also has `data.quote`, the token of the quote the order was placed from (`null` if there was none), so you can match an order to the quote you created.

| Type | Event | Status | Fired When |
| - | - | - | - |
| `quote` | `status_update` | `requested` | A quote has been created and is awaiting review by our team. |
| `quote` | `status_update` | `ready` | The quote has been reviewed and priced, and is ready for payment. |
| `quote` | `status_update` | `approved` | The quote has been approved and added to an invoice (accounts with invoicing enabled). |
| `quote` | `status_update` | `paid` | The quote has been paid and converted into an order. |
| `quote` | `status_update` | `cancelled` | The quote has been cancelled. |
| `order` | `created` | `created` | An order has been created, whether from a paid quote, an invoice, or a direct checkout. |
| `order` | `status_update` | `in_progress` | Work on the order has begun. |
| `order` | `status_update` | `on_hold` | The order has been placed on hold, most commonly when the page or word count needs to be adjusted before work can continue. |
| `order` | `status_update` | `in_review` | The completed translations are ready for review and approval. |
| `order` | `file_created` | — | A translation file has become available on the order: every translation when the order enters review, or the replacement file after a revision is fulfilled. The `target` is the file's token and `data.file` contains the same file object returned in the order's `files` property. |
| `order` | `file_deleted` | — | A translation file is no longer available on the order: it was replaced by a revision or the order left the review stage. `data.file` contains the file's `id`, `name`, and `collection`. |
| `order` | `status_update` | `approved` | Every translation in the order has been approved. |
| `order` | `status_update` | `completed` | The order is complete and the final files are available. |
| `order` | `status_update` | `refunded` | The order has been refunded. |
| `order` | `status_update` | `voided` | The order has been voided. |

For file events, the `target` is the token of the file itself, `data.token` repeats the file token, `data.order` contains the order token, and `url` points to the order, which can be fetched for the current file list. File events are delivered at least once — deduplicate on the file token if your endpoint may receive the same event twice. The temporary `url` and `download_url` links inside `data.file` expire after 1 hour; fetch the order for fresh links.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.