Webhooks

Pipevideo uses Svix to deliver webhooks when video generations complete. Configure your endpoints in the Svix portal, then receive video.generation.completed events with generation status and output URLs.

Setup via Svix portal

1. Sign in to the Pipevideo dashboard (or http://localhost:3000 for local development).
2. Select your organization.
3. Go to Webhooks in the sidebar (or navigate to /webhooks).
4. The Svix app portal opens in an iframe. Use it to:
   • Add endpoint — Enter your webhook URL (e.g. https://your-app.com/api/webhooks/pipevideo).
   • Subscribe to events — Enable video.generation.completed.
   • Copy signing secret — Use it to verify webhook signatures (see Verifying signatures).

Event types

This event is sent for both successful completions and failures (e.g. credit reservation failure, provider timeout, or generation error). Use the status field in the payload to distinguish outcomes.

Payload schema

Each webhook payload is a JSON object with the following fields:

Example: completed generation

{
  "eventType": "video.generation.completed",
  "generationId": "gen_abc123xyz",
  "status": "completed",
  "outputUrl": "https://storage.example.com/videos/abc123.mp4"
}

Example: failed generation

{
  "eventType": "video.generation.completed",
  "generationId": "gen_abc123xyz",
  "status": "failed",
  "errorMessage": "Provider callback timed out"
}

Verifying signatures

Svix signs each webhook with an HMAC. Verify the request before processing it to ensure it came from Pipevideo.

Svix sends these headers:

• svix-id — Unique message ID
• svix-timestamp — Unix timestamp (seconds)
• svix-signature — Signature (format: v1,signature)

Use your endpoint's signing secret from the Svix portal. Example verification (Node.js with the svix package):

import { Webhook } from "svix";

const wh = new Webhook(process.env.PIPEVIDEO_WEBHOOK_SECRET);
const payload = await req.text();
const headers = {
  "svix-id": req.headers.get("svix-id"),
  "svix-timestamp": req.headers.get("svix-timestamp"),
  "svix-signature": req.headers.get("svix-signature"),
};

const body = wh.verify(payload, headers);
// body is the parsed JSON payload

Reject requests with invalid or missing signatures (return 401 Unauthorized).

Retry behavior

Svix retries failed deliveries using an exponential backoff schedule. Your endpoint should return a 2xx status within 15 seconds for the delivery to be considered successful.

Retry schedule

Success criteria

• Success: Your endpoint returns any 2xx status (200–299) within 15 seconds.
• Failure: Any other response (including 3xx redirects), timeout, or connection error triggers a retry.

After retries exhausted

When all retries fail, Svix marks the message as Failed and sends an operational webhook (message.attempt.exhausted) to notify you. Endpoints that fail repeatedly over 5 days (with multiple failures within 24 hours) may be automatically disabled.

Best practices

1. Respond quickly — Process the webhook asynchronously if needed; return 200 immediately and handle the payload in a background job.
2. Be idempotent — The same event may be delivered more than once; use generationId to deduplicate.
3. Return 2xx only on success — Return 500 or another non-2xx if you cannot process the payload, so Svix will retry.

Next steps

• Quickstart — Submit your first video generation.
• Models — Browse available models and pricing.