Webhooks & Callbacks

​

Enabling Callbacks

curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/veo-3.1-fast",
    "input": {
      "prompt": "A cat walking on the beach at sunset"
    },
    "callback_url": "https://your-server.com/webhook"
  }'

​

Webhook Payload Format

​

Success Payload

{
  "task_id": "abc123def456",
  "status": "completed",
  "data": {
    "video_url": "https://cdn.unifically.com/outputs/abc123.mp4"
  }
}

​

Failure Payload

{
  "task_id": "abc123def456",
  "status": "failed",
  "error_message": "Description of what went wrong"
}

​

Request Details

• Method: POST
• Content-Type: application/json
• Body: JSON payload as shown above

​

Webhook Security

1. Authenticity — the request really came from Unifically.
2. Integrity — the payload was not modified in transit. The signature covers the entire request body, so changing even one byte invalidates it.

​

Enabling signing

x-webhook-timestamp: 1788212345
x-webhook-signature: 8f3a2c7d...e91b

signature = hex( HMAC-SHA256( key = your signing secret,
                              message = timestamp + "." + raw_request_body ) )

​

Verifying a delivery

1. Read the two x-webhook-* headers. If signing is enabled and either is missing → reject.
2. Recompute the HMAC over timestamp + "." + raw body, using the header value and the raw request bytes — not re-serialized JSON.
3. Compare with a constant-time comparison. On mismatch, respond 401 and do not process the payload.
4. (Optional, recommended) Check timestamp freshness to block replay of captured deliveries. The tolerance is entirely your choice — the examples below use 5 minutes, but tighten, loosen, or remove it to match your needs. Unifically does not enforce any window; the timestamp is signed so you can trust it either way.

const crypto = require('crypto');

// Keep the raw bytes; express.json() alone discards them after parsing.
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

// Replay tolerance is YOUR policy: adjust freely, or set to Infinity to skip.
const TIMESTAMP_TOLERANCE_SECONDS = 300;

function verifyUnifically(req) {
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];
  if (!timestamp || !/^[a-f0-9]{64}$/.test(signature || '')) return false;

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TIMESTAMP_TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac('sha256', process.env.UNIFICALLY_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

app.post('/webhook', (req, res) => {
  if (!verifyUnifically(req)) return res.sendStatus(401);
  // req.body is now trusted
  res.sendStatus(200);
});

import hmac, hashlib, os, re, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["UNIFICALLY_WEBHOOK_SECRET"].encode()
# Replay tolerance is YOUR policy: adjust freely, or remove the check to skip.
TIMESTAMP_TOLERANCE_SECONDS = 300

def verify_unifically(req) -> bool:
    timestamp = req.headers.get("x-webhook-timestamp", "")
    signature = req.headers.get("x-webhook-signature", "")
    if not timestamp or not re.fullmatch(r"[a-f0-9]{64}", signature):
        return False

    if abs(time.time() - int(timestamp)) > TIMESTAMP_TOLERANCE_SECONDS:
        return False

    message = f"{timestamp}.".encode() + req.get_data()  # raw bytes
    expected = hmac.new(SECRET, message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/webhook")
def webhook():
    if not verify_unifically(request):
        abort(401)
    # request.json is now trusted
    return "", 200

​

Common mistakes

• Verifying against re-serialized JSON. JSON.stringify(req.body) may reorder keys or change whitespace and will not match the bytes we signed. Always keep and use the raw request body.
• Comparing with === / ==. String equality leaks timing information. Use crypto.timingSafeEqual / hmac.compare_digest.
• Forgetting what skipping the timestamp check means. It’s your call to make — but without any freshness window, a captured delivery stays replayable forever. If you skip it, deduplicate on task_id instead.
• Reading the timestamp from anywhere else. Verify with the exact x-webhook-timestamp header value — it’s part of the signed message, so a forged timestamp breaks the signature by itself.

​

Rotating and disabling

• Reset secret (dashboard) rotates the secret. Deliveries signed with the old secret stop verifying immediately, so update your server’s environment right after resetting. Use this if the secret may have leaked.
• Disabling the toggle stops signing; callbacks are delivered without signature headers again. Your secret is kept, so re-enabling later restores it and your server needs no change.

​

Delivery Retries

​

Manual redelivery

​

Best Practices

1. Respond quickly — Return a 2xx status code within a few seconds to acknowledge receipt. Process the payload asynchronously if needed.
2. Verify webhook origin — Enable webhook signing and verify the x-webhook-signature header as described above.
3. Handle duplicates — The same webhook may be delivered more than once (retries, manual redelivery); use task_id to deduplicate.
4. Validate URLs — Ensure your callback URL is publicly accessible and accepts POST requests.

​

Example Handler

// Express.js example
app.post('/webhook', (req, res) => {
  const { task_id, status, data, error_message } = req.body;

  // Acknowledge immediately
  res.status(200).send('OK');

  if (status === 'completed') {
    const url = data.video_url || data.image_url || data.audio_url;
    console.log(`Task ${task_id} completed: ${url}`);
    // Process the completed task...
  } else if (status === 'failed') {
    console.error(`Task ${task_id} failed: ${error_message}`);
    // Handle the failure...
  }
});