🪝Webhooks

Webhooks allow you to receive real-time updates when new Variations are created. By setting up a webhook, your application can automatically receive information about these events without the need for constant polling.

How Webhooks Work

When creating a Render or Variation, include a webhook_url parameter:

{
"config": { ... },
"image_url": "https://example.com/room.jpg",
"variation_count": 3,
"webhook_url": "https://your-app.com/webhooks/renders"
}

Your endpoint will receive separate POST requests for:

• Each Variation's completion or error state

• Analysis results (when using the analyze endpoint)

For example, if you create a render with 3 Variations, you'll receive 3 webhook responses once the Variations either complete or fail. You will not receive a separate webhook response for the parent Render.

Variation Webhook Response Types

There are 2 Variation webhook payload types: done and error.

`Done` response schema

{
"render_id": "rnd_abc123", // the parent render id
"variation_id": "var_xyz789",
"variation_type": "staging",
"base_variation_id": "var_removal123", // if using a base variation from a removal
"timestamp": 1634567890123,
"event_type": "done",
"result": {
    "url":"https://results.example.com/image.jpg",
    "optimized_url":"https://results.example.com/image_optimized.webp",
    "thumbnail_url":"https://results.example.com/image_thumb.jpg"
    }
}

When using Multi-View Staging the result object will be returned as an array of objects

`Error` response schema

{
"render_id": "rnd_abc123",
"variation_id": "var_xyz789",
"variation_type": "staging",
"timestamp": 1634567890123,
"event_type": "error",
"error_message": "Failed to process image"
}

Analysis Webhook Response Types

Best Practices

1. Acknowledge Quickly: Return a 200 status code as soon as you receive the webhook. Process the payload asynchronously if needed.

2. Handle Retries: Webhooks will be retried up to 3 times if your endpoint fails to respond with a 200 status.

3. Store Base Variation IDs: For staging variations, the base_variation_id links to the removal variation it was based on (if a base variation was used or the removal mode was set to auto).

4. Track Event Types: Different event_type values indicate different stages:

   • update: Status changes and progress

   • done: Processing complete

   • error: Processing failed

   • analysis_completion: Analysis complete

   • analysis_error: Analysis failed

Testing Webhooks

We recommend using tools like webhook.site for testing webhook integration before setting up your production endpoint.