Webhooks
Receive HMAC-signed events for every product change and finished export, retried until your endpoint answers, and verify their signatures.
Instead of polling, register a webhook endpoint and Viewrium will POST to it whenever something happens to one of your products - created, generating, finished, reviewed, published, edited or deleted - and when a background export is ready. Every delivery is HMAC-signed so you can verify it came from Viewrium, and a delivery your endpoint does not acknowledge is retried.
Events
| Event | Fired when | Extra fields in data |
|---|---|---|
product.created | A product is committed - from the dashboard, the API or Shopify. | source: dashboard, api or shopify |
product.generating | An order (or a painting's rebuild) starts new work on an existing product. | image_ids, model |
product.completed | A run finishes. The payload says what shipped - including a model that failed. | |
product.failed | The run itself failed. | reason |
product.reviewed | A review decision changes: the product's status, an image's or the model's review. | changes |
product.published | The product is published. | reason: manual |
product.unpublished | The product is unpublished - by you, or because a plan change left more published products than the plan includes. | reason: manual or plan_limit |
product.updated | A setting changes: title, custom id, tags, dimensions (or a rescale), display settings, an image's filename, alt text, background or shadow. | changed_fields |
product.deleted | The product is deleted, alone or in a batch. | Only id and custom_id |
export.ready | A large export finished in the background is ready to download. | Only product_ids, image_count, failed_count |
A failed model is not a failed product: the run completed, so it arrives as
product.completed with model_status: "failed". Branch on model_status, not on the event.
model.readyandmodel.failedare deprecated scan-era names. An endpoint may still list them, but they are never sent - subscribe to theproduct.*events.
Register an endpoint
Create an endpoint in the dashboard, or with the API. Creating one returns a signing secret
(prefixed whsec_) - store it; you use it to verify deliveries. An endpoint belongs to your
organization.
from viewrium import Viewrium, WebhookEndpointCreateRequest, WebhookEventType
client = Viewrium("sk_live_...")
endpoint = client.webhooks.create(
WebhookEndpointCreateRequest(
url="https://api.yourapp.com/hooks/viewrium",
events=[
WebhookEventType.PRODUCT_COMPLETED,
WebhookEventType.PRODUCT_FAILED,
WebhookEventType.PRODUCT_PUBLISHED,
],
)
)
print(endpoint.signing_secret) # whsec_...import { Viewrium } from "@viewrium/sdk";
const client = new Viewrium({ apiKey: "sk_live_..." });
const endpoint = await client.webhooks.create({
url: "https://api.yourapp.com/hooks/viewrium",
events: ["product.completed", "product.failed", "product.published"],
});
console.log(endpoint.signing_secret); // whsec_...The delivery
Viewrium sends a POST with a JSON body and these headers:
| Header | Value |
|---|---|
Viewrium-Signature | t=<unix-timestamp>,v1=<hex hmac-sha256> |
Viewrium-Event-Id | Unique id for this event - the same on every retry |
Viewrium-Event-Type | The event, e.g. product.completed |
User-Agent | Viewrium-Webhooks/1.0 |
The body is a JSON envelope: the event's id (the same as Viewrium-Event-Id), its type, when
it happened, and data:
{
"id": "6f1c...-event-uuid",
"type": "product.completed",
"created_at": "2026-09-16T12:34:56+00:00",
"data": {
"id": "0b1e...-product-uuid",
"title": "Oak dining chair",
"custom_id": "sku-oak-chair",
"status": "awaiting_review",
"display_status": "awaiting_review",
"published": false,
"images_ordered": true,
"image_count": 4,
"images": [{ "id": "...", "view": "front", "flagged": false }],
"model_status": "ready",
"thumbnail_url": "https://cdn.viewrium.com/.../thumb.jpg"
}
}For every product.* event except product.deleted, data is the product as it is when the
event fires - the fields above - plus the event's own fields. It never carries a storage path,
the analysis, or a URL for the 3D model file (mint a
model ticket when you need to show it). Respond with any
2xx to acknowledge receipt.
Each event's own fields
product.created says where the product came from:
{ "id": "0b1e...", "title": "Oak dining chair", "source": "api" }product.generating names the image rows the new work makes, and whether the model is part of it:
{ "id": "0b1e...", "title": "Oak dining chair", "image_ids": ["9a2e...", "c41b..."], "model": false }product.failed says why the run failed:
{ "id": "0b1e...", "title": "Oak dining chair", "reason": "the model could not be generated" }product.reviewed carries only what changed: the product's status, each image whose review
changed, and the model's review.
{
"id": "0b1e...",
"title": "Oak dining chair",
"changes": {
"status": "ready_to_publish",
"images": [{ "id": "9a2e...", "review_status": "accepted" }],
"model_review_status": "rejected"
}
}product.published and product.unpublished say why: manual (a person, or your API call), or
plan_limit (unpublished to fit the plan's active-product limit):
{ "id": "0b1e...", "title": "Oak dining chair", "published": false, "reason": "plan_limit" }product.updated names the fields that changed, by their API names; an image's settings appear
as images.<field>:
{ "id": "0b1e...", "title": "Oak dining chair", "changed_fields": ["dimensions", "images.alt_override", "title"] }product.deleted carries the two ids you may have stored, read just before the delete:
{ "id": "0b1e...-product-uuid", "custom_id": "sku-oak-chair" }export.ready carries the products in the export, how many images it holds, and how many could
not be finished. The download link goes by email to whoever asked for the export.
{ "product_ids": ["0b1e...", "7d33..."], "image_count": 18, "failed_count": 0 }(The examples above shorten the product to its id and title; a real data carries every
field of the product shown in the envelope.)
Retries
A delivery that does not get a 2xx back - an error status, a timeout (10 seconds) or a
connection failure - is retried. Each event is attempted up to six times:
| Attempt | When |
|---|---|
| 1 | At once |
| 2 | 5 minutes after the first |
| 3 | 30 minutes after the second |
| 4 | 2 hours after the third |
| 5 | 8 hours after the fourth |
| 6 | 24 hours after the fifth |
Every retry sends the same event: the same Viewrium-Event-Id and the same body, freshly
signed. An endpoint is never disabled for failing; disabling or deleting it stops its retries.
Deduplicate on
Viewrium-Event-Id. A retry resends an event your endpoint may already have processed (it did the work but answered too slowly, say), so record the ids you have handled and answer a repeat with2xxwithout doing the work again. Return2xxquickly and do heavy work asynchronously.
Each event is its own delivery, so they can arrive out of order - a retried product.updated can
land after a later one. data is the product as it was when its event fired; read the product
when you need its current state.
Verify the signature
Compute an HMAC-SHA256 over the string "<timestamp>.<raw request body>" using your endpoint's
signing secret, then compare it - in constant time - to the v1 value from the Viewrium-Signature
header. Use the raw request body, exactly as received, not a re-serialized object.
import hashlib
import hmac
def verify(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
timestamp, sent = parts["t"], parts["v1"]
expected = hmac.new(
secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, sent)import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret: string, header: string, rawBody: string): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const { t: timestamp, v1: sent } = parts;
const expected = createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(sent ?? "");
return a.length === b.length && timingSafeEqual(a, b);
}Reject the request (return 4xx) if verification fails. For extra safety against replay, also reject
deliveries whose t timestamp is far from the current time - each retry is signed afresh, so a
genuine retry always carries a current timestamp.
Manage and debug
| Operation | SDK |
|---|---|
| List endpoints | webhooks.list() |
| Retrieve one | webhooks.retrieve(id) |
| Update (url, events, enabled) | webhooks.update(id, ...) |
| Delete | webhooks.delete(id) |
| List recent deliveries | webhooks.listDeliveries(id) / webhooks.list_deliveries(id) |
The deliveries list shows each event's latest attempt - how many attempts were made, the HTTP
status, the timestamps, any error, and next_attempt_at, when the next retry is due (null once
it succeeded or its attempts ran out) - which is the fastest way to see why an endpoint is not
receiving events.