Webhooks

Webhooks let you receive HTTP POST notifications when events occur in your Vidiking account, eliminating the need to poll for job status.

Configuration

Per-Request Callback

Pass a callback URL with any render request to receive a webhook when that job completes.

curl -X POST https://api.vidiking.com/v1/render \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeline": { ... },
    "output": { "format": "mp4", "resolution": "hd" },
    "callback": "https://your-server.com/webhooks/vidiking"
  }'

Global Webhook

Configure a global webhook URL in the dashboard or via the API. This receives notifications for all events.

curl -X PUT https://api.vidiking.com/v1/webhooks \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/vidiking",
    "events": ["render.complete", "render.failed", "wallet.low_balance"],
    "secret": "whsec_your_signing_secret"
  }'

Events

Event	Description
render.complete	A render job finished successfully
render.failed	A render job failed
render.queued	A render job was queued
render.processing	A render job started processing
ai.complete	An AI generation job completed
ai.failed	An AI generation job failed
wallet.low_balance	Wallet balance dropped below threshold
wallet.deposit	Funds were deposited

Payload Format

All webhook payloads follow the same structure.

{
  "event": "render.complete",
  "timestamp": "2025-01-15T10:30:45Z",
  "data": {
    "id": "job_abc123",
    "status": "COMPLETE",
    "url": "https://cdn.vidiking.com/renders/job_abc123.mp4",
    "duration": 10.5,
    "credits_used": 10,
    "wallet_balance": 4510
  }
}

Handling Webhooks

Node.js (Express)

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhooks/vidiking', (req, res) => {
  // Verify signature
  const signature = req.headers['x-vidiking-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'render.complete':
      console.log(`Job ${data.id} complete: ${data.url}`);
      break;
    case 'render.failed':
      console.error(`Job ${data.id} failed: ${data.error}`);
      break;
    case 'wallet.low_balance':
      console.warn(`Low balance: ${data.balance} balance remaining`);
      break;
  }

  res.status(200).send('OK');
});

Python (Flask)

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/vidiking", methods=["POST"])
def webhook():
    # Verify signature
    signature = request.headers.get("x-vidiking-signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if signature != expected:
        return "Invalid signature", 401

    payload = request.json
    event = payload["event"]
    data = payload["data"]

    if event == "render.complete":
        print(f"Job {data['id']} complete: {data['url']}")
    elif event == "render.failed":
        print(f"Job {data['id']} failed: {data.get('error')}")

    return "OK", 200

Signature Verification

Every webhook request includes an x-vidiking-signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.

Always verify this signature before processing the webhook to ensure the request is genuine.

x-vidiking-signature: sha256=a1b2c3d4e5f6...

Retry Policy

If your endpoint does not respond with a 2xx status code within 10 seconds, Vidiking retries the delivery.

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	1 hour
5th retry	6 hours

After 5 failed retries, the webhook is marked as failed. You can view failed deliveries and replay them in the dashboard under Settings > Webhooks > Delivery Log.

Testing Webhooks

Use the dashboard webhook tester or a tool like ngrok to expose your local server during development.

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL as your callback
curl -X POST https://api.vidiking.com/v1/render \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeline": { ... },
    "callback": "https://abc123.ngrok.io/webhooks/vidiking"
  }'