> For the complete documentation index, see [llms.txt](https://doc.aihomedesign.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.aihomedesign.com/getting-started/webhook-reference.md).

# Webhook Reference

When a process finishes, the platform sends an HTTP `POST` request to your registered webhook URL with the result payload. This page describes the full payload shape, delivery rules, and requirements for your endpoint.

***

### Registering Your Webhook URL

The images below show how to configure your webhook in the dashboard so you can automatically receive your generated photos as soon as they are ready.

Click the **API** icon in the left sidebar of the dashboard. Inside the API section, you will find a **Webhook** section where you can configure your webhook URL for receiving generated photo updates.

<figure><img src="/files/IBEyTeT78F8mPAMPaA5l" alt=""><figcaption></figcaption></figure>

Click the **Add Endpoint** button to create a new webhook endpoint for receiving generated photo updates.

<figure><img src="/files/507r6uORWF6BcEHTSDwn" alt=""><figcaption></figcaption></figure>

After clicking **Add Endpoint**, enter your webhook URL and configure your preferred settings to start receiving generated photo automatically.&#x20;

<figure><img src="/files/T0sZXRJBTmK9UrJYlHYo" alt=""><figcaption></figcaption></figure>

***

### Payload

The platform sends this JSON body when a process completes:

```json
{
  "event": "process.completed",
  "process_id": "69a6bb11a374700bff4a1333",
  "order_id": "69a6aa03a374700bff4a1328",
  "tool": "tool-virtual-staging",
  "status": "done",
  "final_assets": [
    {
      "asset_id": "69a6cc22a374700bff4a1400",
      "asset_type": "image",
      "temp_src": "https://cdn.aihomedesign.com/result.jpg",
      "temp_thumbnail_src": "https://cdn.aihomedesign.com/result_thumb.jpg"
    }
  ]
}
```

#### Payload fields

| Field                               | Type   | Description                                                            |
| ----------------------------------- | ------ | ---------------------------------------------------------------------- |
| `event`                             | string | Always `process.completed`                                             |
| `process_id`                        | string | ID of the completed process — matches what `POST /v3/process` returned |
| `order_id`                          | string | ID of the order this process belongs to                                |
| `tool`                              | string | Tool slug that was run (e.g. `tool-virtual-staging`)                   |
| `status`                            | string | `done` on success, `failed` on error                                   |
| `final_assets`                      | array  | The output images (empty on failure)                                   |
| `final_assets[].asset_id`           | string | Unique ID of the output asset                                          |
| `final_assets[].asset_type`         | string | Always `image` for generated results                                   |
| `final_assets[].temp_src`           | string | Direct URL to the full-resolution output image                         |
| `final_assets[].temp_thumbnail_src` | string | Direct URL to a smaller thumbnail                                      |

***

### Requirements for Your Endpoint

| Requirement         | Detail                                                               |
| ------------------- | -------------------------------------------------------------------- |
| **HTTPS**           | Your webhook URL must use `https://`                                 |
| **Response time**   | Must return a `2xx` status code within **10 seconds**                |
| **Retry behaviour** | The platform retries delivery on non-`2xx` responses                 |
| **Idempotency**     | Your handler should tolerate receiving the same event more than once |

***

### Polling Fallback

If you cannot expose a public webhook endpoint, you can poll instead:

```bash
curl 'https://api.aihomedesign.com/v3/process/<process_id>' \
  --header 'x-api-key: <your_api_key>'
```

Check the `status` field in the response:

| Status       | Meaning                                         |
| ------------ | ----------------------------------------------- |
| `pending`    | Queued, not yet started                         |
| `processing` | AI is running                                   |
| `done`       | Finished — read `final_assets` for results      |
| `failed`     | Something went wrong — retry or contact support |

> Avoid polling more than once every **5 seconds** to prevent rate-limiting.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.aihomedesign.com/getting-started/webhook-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.