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