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"
}
}
type | When |
|---|---|
render.succeeded | render.output.url is ready |
render.failed | The 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:
tis the Unix time the call was signed.v1is the hex HMAC-SHA256 oft, 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
2xxanswer 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/:idfor any render you haven't heard about within 3 minutes. - Redirects aren't followed. Use the final address.
- Answer fast. Return
200first, then do the slow work (saving the image, emailing the customer) in the background. - Expect the unexpected. Ignore a render
idyou've already handled.