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.

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

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

---

Payload

The platform sends this JSON body when a process completes:

{
  "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:

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.