Webhooks

Instead of asking every few seconds, let VizTunr tell your server when a render is done. One signed request per render.

Ask for a webhook#

Add webhook_url when you start a render:

{
  "upload": "upl_269c9fcbc7154983b2124958d8e4c58e",
  "op": "wheels",
  "ref": "https://yourshop.com/images/forged-r1.jpg",
  "webhook_url": "https://yourshop.com/viztunr/webhook"
}

The address must be public and use https. Addresses on private networks or localhost are refused with 400, code parameter_invalid.

What VizTunr sends#

When the render succeeds or fails, VizTunr sends one POST to your webhook_url:

POST /viztunr/webhook HTTP/1.1
Content-Type: application/json
User-Agent: VizTunr-Webhooks/1
VizTunr-Signature: t=1763105811,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "type": "render.succeeded",
  "render": {
    "id": "rnd_b13cf6c43e5a49aabc5b2be8ddbffd60",
    "status": "succeeded",
    "output": { "url": "https://api.viztunr.com/storage/v1/object/public/renders/.../result.png" },
    "...": "the full render object"
  }
}
typeWhen
render.succeededrender.output.url is ready
render.failedThe render failed and was given back; see render.failure

render is the same object GET /v1/renders/:id returns.

Check the signature#

Anyone who learns your webhook address could send it a fake result. Every real call is signed with your API key:

  • t is the Unix time the call was signed.
  • v1 is the hex HMAC-SHA256 of t, a period, and the raw request body, using as the secret the hex SHA-256 of the API key that started the render.

So your server needs nothing new: hash your key once, and check each call against it. Reject calls whose signature doesn't match, and calls more than 5 minutes old.

Node.js#

import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

const secret = createHash('sha256').update(process.env.VIZTUNR_KEY).digest('hex');

// rawBody: the request body exactly as received, before JSON.parse.
export function isValidVizTunrWebhook(rawBody, signatureHeader) {
  const t = /t=(\d+)/.exec(signatureHeader ?? '')?.[1];
  const v1 = /v1=([0-9a-f]{64})/.exec(signatureHeader ?? '')?.[1];
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

PHP#

<?php
function is_valid_viztunr_webhook(string $raw_body, string $signature_header): bool {
    $secret = hash('sha256', getenv('VIZTUNR_KEY'));
    if (!preg_match('/t=(\d+)/', $signature_header, $t) ||
        !preg_match('/v1=([0-9a-f]{64})/', $signature_header, $v1)) {
        return false;
    }
    if (abs(time() - (int) $t[1]) > 300) {
        return false;
    }
    $expected = hash_hmac('sha256', $t[1] . '.' . $raw_body, $secret);
    return hash_equals($expected, $v1[1]);
}

// $raw_body = file_get_contents('php://input');
// $signature = $_SERVER['HTTP_VIZTUNR_SIGNATURE'] ?? '';

Delivery#

  • One attempt. VizTunr calls your address once, right after the render ends, and waits up to 10 seconds. A 2xx answer counts as delivered.
  • No retries. If your server is down, slow, or answers with an error, the call is not repeated. Poll GET /v1/renders/:id for any render you haven't heard about within 3 minutes.
  • Redirects aren't followed. Use the final address.
  • Answer fast. Return 200 first, then do the slow work (saving the image, emailing the customer) in the background.
  • Expect the unexpected. Ignore a render id you've already handled.