Skip to main content
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

1

Register a Webhook URL

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.
2

Job Runs

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

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

Register a webhook by including webhookUrl in your generate request: 
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"
  }'

​
URL Requirements

Your webhook URL must meet the following requirements:
RequirementDetails
ProtocolHTTPS only (HTTP is rejected)
No localhostlocalhost, 127.0.0.1, 0.0.0.0, ::1 are rejected
No private IPs10.*, 192.168.*, 172.16-31.* ranges are rejected
Publicly accessibleYour 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

​
event
string
required
Event type. Currently always job.completed (covers completed, partial, and failed terminal states).
​
jobId
string
required
UUID of the generation job.
​
status
string
required
Terminal job status. One of:
  • completed — all projects finished successfully
  • partial — some projects completed, some failed
  • failed — all projects failed
​
totalProjects
integer
required
Total number of projects in the job.
​
completedProjects
integer
required
Number of projects that completed successfully.
​
failedProjects
integer
required
Number of projects that failed.
​
projects
array
required
Details for each project in the job.

​
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 });
});
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

PropertyDetails
MethodPOST
Content-Typeapplication/json
Timeout10 seconds per attempt — your server must respond within 10 seconds
Retries3 attempts with exponential backoff (immediate → 10s → 60s)
Attempt headerX-Nouvel-Attempt — indicates which attempt number (1, 2, or 3)
Rate limitsWebhook 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:
AttemptDelayTotal elapsed
1Immediate0s
210 seconds~10s
360 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

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);
});
Never trust webhook payloads without verifying the X-Nouvel-Signature header. This prevents attackers from sending fake webhook events to your endpoint.
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.
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);