Webhooks

Webhooks let you receive HTTP notifications when video generation jobs reach a terminal state, eliminating the need to poll the jobs endpoint. When a job completes, fails, or partially completes, Nouvel sends a POST request to your registered URL with the job details.

How It Works

Include a webhookUrl in your POST /api/v1/generate request body. The URL is stored with the job and will receive a notification when the job finishes.

Job Runs

Video generation proceeds as normal. You can still poll the jobs endpoint if desired — webhooks and polling are not mutually exclusive.

Receive Notification

When all projects in the job reach a terminal state (completed, partial, or failed), Nouvel sends a POST to your webhook URL with the full job details.

Registration

curl -X POST https://app.nouvel.ai/api/v1/generate \
  -H "Authorization: Bearer nvl_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/products/protein-powder"],
    "variantCount": 2,
    "webhookUrl": "https://your-server.com/webhooks/nouvel"
  }'

const response = await fetch('https://app.nouvel.ai/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NOUVEL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    urls: ['https://example.com/products/protein-powder'],
    variantCount: 2,
    webhookUrl: 'https://your-server.com/webhooks/nouvel',
  }),
});

URL Requirements

Your webhook URL must meet the following requirements:

Requirement	Details
Protocol	HTTPS only (HTTP is rejected)
No localhost	`localhost`, `127.0.0.1`, `0.0.0.0`, `::1` are rejected
No private IPs	`10.`, `192.168.`, `172.16-31.*` ranges are rejected
Publicly accessible	Your server must be reachable from the public internet

If the webhook URL fails validation, the generate request returns a 400 error and no job is created.

Webhook Payload

When a job reaches a terminal state, Nouvel sends the following POST request to your URL:

POST https://your-server.com/webhooks/nouvel
Content-Type: application/json
X-Nouvel-Signature: a1b2c3d4e5f6...

{
  "event": "job.completed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "totalProjects": 2,
  "completedProjects": 2,
  "failedProjects": 0,
  "projects": [
    {
      "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Protein Powder Ad - Variant 1",
      "status": "completed",
      "videoUrl": "https://app.nouvel.ai/api/cdn/videos/final-xxx.mp4"
    },
    {
      "projectId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "title": "Protein Powder Ad - Variant 2",
      "status": "completed",
      "videoUrl": "https://app.nouvel.ai/api/cdn/videos/final-yyy.mp4"
    }
  ]
}

Payload Fields

string

required

Event type. Currently always job.completed (covers completed, partial, and failed terminal states).

string

required

UUID of the generation job.

string

required

Terminal job status. One of:

completed — all projects finished successfully
partial — some projects completed, some failed
failed — all projects failed

integer

required

Total number of projects in the job.

integer

required

Number of projects that completed successfully.

integer

required

Number of projects that failed.

array

required

Details for each project in the job.

Show Project object

string

required

UUID of the project.

string

required

Generated title for the video.

string

required

Project status (completed or failed).

string

URL to the final video file. Only present when status is completed.

Signature Verification

Every webhook request includes an X-Nouvel-Signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature to ensure the request is genuinely from Nouvel.

import crypto from 'crypto';

function verifyWebhookSignature(
  body: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

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

// In your webhook handler:
app.post('/webhooks/nouvel', (req, res) => {
  const signature = req.headers['x-nouvel-signature'] as string;
  const rawBody = JSON.stringify(req.body);

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook...
  const { event, jobId, status, projects } = req.body;
  console.log(`Job ${jobId}: ${status} (${projects.length} projects)`);

  res.status(200).json({ received: true });
});

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

app = Flask(__name__)

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/nouvel', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Nouvel-Signature', '')

    if not verify_webhook_signature(request.data, signature, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    data = request.json
    print(f"Job {data['jobId']}: {data['status']}")

    return jsonify({'received': True}), 200

The signing secret is the WEBHOOK_SIGNING_SECRET environment variable configured on the Nouvel server. Contact support@nouvel.ai to obtain your webhook signing secret for signature verification.

Delivery Behavior

Property	Details
Method	`POST`
Content-Type	`application/json`
Timeout	10 seconds per attempt — your server must respond within 10 seconds
Retries	3 attempts with exponential backoff (immediate → 10s → 60s)
Attempt header	`X-Nouvel-Attempt` — indicates which attempt number (1, 2, or 3)
Rate limits	Webhook deliveries do not count toward your API rate limit

Retry Logic

If your endpoint is temporarily unreachable or returns a server error (5xx), Nouvel retries with exponential backoff:

Attempt	Delay	Total elapsed
1	Immediate	0s
2	10 seconds	~10s
3	60 seconds	~70s

Non-retryable errors: HTTP 4xx responses (except 429 Too Many Requests) are treated as permanent failures and are NOT retried. Ensure your endpoint returns 200 on success.

While retries cover most transient failures, we still recommend periodic polling of the jobs endpoint as a safety net for mission-critical workflows.

Timing

The webhook fires when the job status endpoint detects that a job has transitioned to a terminal state. This happens during a status poll — not at the exact moment of completion. In practice, this means:

If you’re polling the job status endpoint, the webhook fires during one of your polls
If you’re not polling, the webhook fires when any poll (including internal monitoring) checks the job

For the fastest notification, combine webhooks with periodic polling. The webhook will typically arrive within seconds of job completion if you’re actively polling.

Best Practices

Respond quickly

Your webhook endpoint should return a 200 status code within 10 seconds. If you need to do heavy processing, accept the webhook immediately and process asynchronously.

app.post('/webhooks/nouvel', async (req, res) => {
  // Respond immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  processWebhook(req.body).catch(console.error);
});

Always verify signatures

Never trust webhook payloads without verifying the X-Nouvel-Signature header. This prevents attackers from sending fake webhook events to your endpoint.

Handle idempotency

Design your webhook handler to be idempotent. Since webhooks retry up to 3 times, your endpoint may receive the same event multiple times. Use the jobId as a deduplication key.

Use polling as fallback

While webhooks now retry up to 3 times, implement periodic polling of the jobs endpoint as a safety net for mission-critical workflows. Check for completed jobs that may have been missed if all retry attempts fail.

Example: Full Integration

Here’s a complete example combining webhook registration with a handler:

// 1. Submit generation with webhook
const job = await fetch('https://app.nouvel.ai/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NOUVEL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    urls: ['https://example.com/products/protein-powder'],
    variantCount: 2,
    webhookUrl: 'https://your-server.com/webhooks/nouvel',
  }),
}).then(r => r.json());

console.log(`Job ${job.jobId} started. Waiting for webhook...`);

// 2. Handle webhook (Express server)
import express from 'express';
import crypto from 'crypto';

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

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

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const { jobId, status, projects } = req.body;

  // Process completed videos
  for (const project of projects) {
    if (project.status === 'completed') {
      console.log(`Video ready: ${project.videoUrl}`);
      // Download, publish, notify your users, etc.
    }
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Getting Started

Core Concepts

Video Generation

Projects

Publishing

Analytics

AI Copilot

How It Works

Registration

URL Requirements

Webhook Payload

Payload Fields

Signature Verification

Delivery Behavior

Retry Logic

Timing

Best Practices

Example: Full Integration

​How It Works

​Registration

​URL Requirements

​Webhook Payload

​Payload Fields

​Signature Verification

​Delivery Behavior

​Retry Logic

​Timing

​Best Practices

​Example: Full Integration

How It Works

Registration

URL Requirements

Webhook Payload

Payload Fields

Signature Verification

Delivery Behavior

Retry Logic

Timing

Best Practices

Example: Full Integration