Viewrium Docs

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

EventFired whenExtra fields in data
product.createdA product is committed - from the dashboard, the API or Shopify.source: dashboard, api or shopify
product.generatingAn order (or a painting's rebuild) starts new work on an existing product.image_ids, model
product.completedA run finishes. The payload says what shipped - including a model that failed.
product.failedThe run itself failed.reason
product.reviewedA review decision changes: the product's status, an image's or the model's review.changes
product.publishedThe product is published.reason: manual
product.unpublishedThe product is unpublished - by you, or because a plan change left more published products than the plan includes.reason: manual or plan_limit
product.updatedA setting changes: title, custom id, tags, dimensions (or a rescale), display settings, an image's filename, alt text, background or shadow.changed_fields
product.deletedThe product is deleted, alone or in a batch.Only id and custom_id
export.readyA 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.ready and model.failed are deprecated scan-era names. An endpoint may still list them, but they are never sent - subscribe to the product.* 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.

Python
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_...
TypeScript
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:

HeaderValue
Viewrium-Signaturet=<unix-timestamp>,v1=<hex hmac-sha256>
Viewrium-Event-IdUnique id for this event - the same on every retry
Viewrium-Event-TypeThe event, e.g. product.completed
User-AgentViewrium-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:

AttemptWhen
1At once
25 minutes after the first
330 minutes after the second
42 hours after the third
58 hours after the fourth
624 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 with 2xx without doing the work again. Return 2xx quickly 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.

Python
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)
TypeScript
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

OperationSDK
List endpointswebhooks.list()
Retrieve onewebhooks.retrieve(id)
Update (url, events, enabled)webhooks.update(id, ...)
Deletewebhooks.delete(id)
List recent deliverieswebhooks.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.

On this page