How do I register a callback URL for my store?

Register a callback URL in the Ratio Ready dashboard or create it via the REST API. Use HTTPS and a stable host. We provide a free Make.com blueprint that wires callbacks into common flows; setup takes 30–45 minutes. After registration, run a dry-run job to verify a 2xx response and signature validation. Remember staging and production should use separate URLs.

What exactly is in the webhook when a wall art job completes?

On completion you get job_id, job_type='wall_art', status='completed', credit_cost (59 for wall art), timestamps, and an assets object. Assets include five 300 DPI print files (2:3, 3:4, 4:5, 11:14, ISO A1), up to 20 mockup URLs, a 15-second 1:1 listing video URL, a listing-copy PDF, and a Drive share link. Processing takes about 3–5 minutes after a 2-minute upload.

How do I verify the webhook is really from Ratio Ready?

Verify the HMAC signature in header X-RatioReady-Signature. Compute HMAC-SHA256 over the raw request body using your API secret and compare with a constant-time check. Optionally validate X-RatioReady-Timestamp and reject payloads outside a 300-second window to prevent replay attacks. If verification fails, respond 401 and log the request.

What happens if my server returns errors or is down?

We retry failed deliveries with exponential backoff (≈1m, 5m, 20m, 1h, 4h). After the final retry the callback is placed in a dead-letter queue and the job is flagged in your dashboard. You can re-push assets manually or reconfigure the endpoint. The job itself remains completed; credits are charged at completion, not on delivery attempts.

Can I poll job status instead of using webhooks?

Yes. The REST API supports polling via /jobs/:id. Polling is viable for low volume. Webhooks scale better: fewer API calls, immediate delivery, and predictable operations. If you use Make.com, the included blueprint runs on the free tier (1,000 ops/month ≈ 80–125 listings/month), making webhooks practical for production pipelines.

Do callbacks tell me how many credits were used?

Yes. Each callback includes a credit_cost field. Wall art jobs are 59 credits. Posters are 55 credits. Clipart batches start at 29 credits plus 10 credits per additional 5 images. Credits are charged when the job reaches completed status. New accounts get 75 free credits on signup.

How should I handle duplicate callbacks and idempotency?

Design your endpoint to be idempotent. Use job_id to deduplicate. A safe pattern: respond 200 immediately after signature verification, then check a persistent store for job_id. If job_id is new, process and persist; if seen, skip. Retain processed job_ids for a minimum of 24 hours to handle retry storms and late duplicates.

Developer reference

Webhook callbacks for completed jobs

Polling works for ad-hoc scripts. For production at scale, register a webhook callback URL and Ratio Ready posts to it the moment a job finishes — signed with HMAC, retried on failure, ready to drop into your pipeline.

MA By Mac 3 min read May 5, 2026

The short answer

mockup generation webhook callback is the production-safe way to stop refreshing dashboards and burning afternoons exporting files. Sellers shipping 5–50 listings a month outgrow manual prep fast: upscales, five print ratios, mockups, a listing video, and tags. Webhook callbacks deliver job completion, asset URLs, and credit usage the moment a job finishes. Register a callback URL in the dashboard or via the REST API. Then let Ratio Ready push completed wall art, poster, or clipart packages to your system. Get started at app.ratioready.com. 75 free credits on signup. Production-first. No fluff.

how callbacks fit in production

Webhooks move Ratio Ready from a desktop chore to a live production step. A submitted job runs on our servers. When it finishes, we POST a callback to your URL with job status, download links, and the credit charge. Wall art jobs include 5 print sizes (2:3, 3:4, 4:5, 11:14, ISO A1) at 300 DPI, up to 20 mockups, a 15-second 1:1 listing video, a listing-copy PDF, and a Drive share link. Posters return a single 300 DPI print file and mockups (55 credits). Clipart batches return 1–50 images with print files and listing previews (29 credits base + 10 credits per extra 5 images).

Per-listing timing: 2 minutes to upload, then 3–5 minutes processing. A webhook pushes the result the moment processing completes. This keeps your listing pipeline deterministic and traceable.

registering a callback URL

Register a callback URL in two ways: add it in the Ratio Ready dashboard or create it programmatically with the REST API. Use HTTPS. Use a stable domain and a single path per environment (staging/production).

We include a free Make.com blueprint that connects callbacks into common flows. The blueprint runs on the free Make.com tier (1,000 ops/month ≈ 80–125 listings/month). One-time setup is 30–45 minutes. After registration, test with a dry-run job from the dashboard to confirm 2xx responses and signature verification.

callback payload shape

We send a JSON POST on job events. Key fields you will receive:

job_id — string, unique job identifier.
job_type — "wall_art" | "poster" | "clipart".
status — "queued" | "processing" | "completed" | "failed".
credit_cost — integer, credits charged on completion.
assets — object with arrays: download_urls, mockup_urls, video_url, listing_pdf, drive_share_link (nullable if not applicable).
submitted_at and completed_at — ISO 8601 timestamps.

Wall art completed payload will include five 300 DPI print files, up to 20 mockups, a 15-second listing video, a listing-copy PDF, and a Drive folder link. Poster payloads omit the Drive/shareable PDF. Clipart batches include batched listing previews and optional watermark info.

hmac signature verification

Every webhook includes an HMAC signature header. Use it to verify the payload before processing. Header: X-RatioReady-Signature. We compute HMAC-SHA256 over the raw request body with your API secret. Compare using a constant-time function.

Optional: we also include X-RatioReady-Timestamp. Reject payloads outside a 300-second clock skew to prevent replay. If verification fails, respond 401 and log the event. If valid, respond 200 immediately and enqueue background processing.

retry behaviour, dead-letter handling, and polling alternative

If your endpoint responds non-2xx, we retry delivery. Retries use exponential backoff: roughly 1 minute, 5 minutes, 20 minutes, 1 hour, and 4 hours. After the final failed attempt the callback goes to a dead-letter queue and the job is flagged in your dashboard for manual review. We also surface delivery failures in the dashboard so you can reconfigure endpoints.

Polling is supported via the REST API (/jobs/:id). Polling works for small volumes. Webhooks are better at production scale: fewer requests, predictable ops, and near-real-time notifications. Use the Make.com blueprint or our REST API for integrations with n8n, Zapier, or custom code.

Frequently asked questions

Keep reading

REST API reference

Where webhooks fit alongside the rest of the API

Mockup generator API

The endpoint your webhook is most likely to listen to

Batch processing API

Bulk-job endpoints that emit per-image webhook callbacks

Headless mockup pipeline

End-to-end pattern using webhooks instead of polling

Add webhook callbacks to your pipeline

75 free credits on signup. Register a callback URL in seconds and stop burning operations on poll loops.

Get your API key