Webhooks

Receive real-time notifications about video generation events

Overview

Webhooks allow you to receive HTTP POST notifications when specific events occur, such as when a video generation completes or fails. This is more efficient than polling the API.

Create Webhook

POST/webhooks

Request Body

Parameter	Type	Required	Description
url	string	Yes	Your webhook endpoint URL
events	array	Yes	Event types to listen for

Example Request

curl -X POST https://api.prism.video/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/prism",
    "events": ["video.completed", "video.failed"]
  }'

Event Types

Event	Description
video.completed	Video generation finished successfully
video.failed	Video generation failed

Webhook Payload

When an event occurs, Prism will send a POST request to your webhook URL:

{
  "event": "video.completed",
  "timestamp": "2026-01-13T14:35:00Z",
  "data": {
    "id": "gen_abc123xyz",
    "status": "completed",
    "prompt": "A serene mountain lake at sunset",
    "provider": "runway",
    "duration": 6,
    "video_url": "https://storage.prism.video/videos/gen_abc123xyz.mp4",
    "thumbnail_url": "https://storage.prism.video/thumbnails/gen_abc123xyz.jpg",
    "created_at": "2026-01-13T14:30:00Z"
  }
}

Signature Verification

Each webhook includes a signature in the X-Prism-Signature header. Verify this to ensure the request came from Prism:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

List Webhooks

GET/webhooks

curl https://api.prism.video/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Always verify the webhook signature
Respond with a 200 status code quickly (within 5 seconds)
Process webhook data asynchronously if needed
Implement retry logic for failed processing
Use HTTPS endpoints in production