Webhooks

Overview

Instead of polling GET /shorts/:id/status every 10 seconds, you can provide a webhookUrl when creating a short. The API will send an HTTP POST to your URL when processing completes or fails.

This is ideal for:

Automation platforms — trigger n8n, Zapier, or Make workflows on completion
Backend pipelines — process results immediately without polling loops
Serverless functions — use AWS Lambda, Vercel, or Cloudflare Workers as receivers

How it works

Include webhookUrl in your POST /shorts/create request
The API validates and stores the URL
When processing finishes (completed or failed), the API sends an HTTP POST to your URL
Your server responds with any 2xx status code to acknowledge receipt

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "start": 0,
  "end": 600,
  "webhookUrl": "https://your-server.com/webhook/ssemble"
}

Events

`shorts.completed`

Sent when all clips have been generated successfully.

{
  "event": "shorts.completed",
  "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "completed",
  "timestamp": "2026-03-30T12:00:00.000Z",
  "data": {
    "shorts": [
      {
        "id": "665a1b2c3d4e5f6a7b8c9d10",
        "title": "The Most Surprising Moment",
        "video_url": "https://storage.googleapis.com/...",
        "duration": 45,
        "viral_score": 8.5
      },
      {
        "id": "665a1b2c3d4e5f6a7b8c9d11",
        "title": "Key Insight Everyone Missed",
        "video_url": "https://storage.googleapis.com/...",
        "duration": 58,
        "viral_score": 7.2
      }
    ]
  }
}

`shorts.failed`

Sent when processing fails. Credits are automatically refunded.

{
  "event": "shorts.failed",
  "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "failed",
  "timestamp": "2026-03-30T12:05:00.000Z",
  "data": {
    "failureReason": "Video download failed: URL returned 403 Forbidden"
  }
}

Payload fields

Field	Type	Description
`event`	string	Event type: `shorts.completed` or `shorts.failed`
`requestId`	string	The request ID from the create response
`status`	string	`completed` or `failed`
`timestamp`	string	ISO 8601 timestamp of when the event occurred
`data`	object	Event-specific data (see above)

Shorts fields (in `data.shorts`)

Field	Type	Description
`id`	string	Unique clip identifier
`title`	string	AI-generated title for the clip
`video_url`	string	Direct URL to the generated video file
`duration`	number	Clip duration in seconds
`viral_score`	number	AI-predicted engagement score (0-10)

Retry behavior

If your server doesn't respond with a 2xx status code (or the request times out), the API retries up to 3 times with increasing delays:

Attempt	Delay
1st	Immediate
2nd	1 second
3rd	3 seconds

Each attempt has a 10-second timeout. If all attempts fail, the webhook is abandoned — but this does not affect the request itself. Your clips are still available via GET /shorts/:id.

URL requirements

Must be a valid http:// or https:// URL
Must be publicly accessible from the internet
Maximum URL length: 2,048 characters
Cannot point to:
- localhost or 127.0.0.1
- Private IP ranges (10.x, 172.16-31.x, 192.168.x)
- Cloud metadata endpoints (169.254.x)

Example receivers

Express.js (Node.js)

const express = require('express');
const app = express();
app.use(express.json());
 
app.post('/webhook/ssemble', (req, res) => {
  const { event, requestId, data } = req.body;
 
  if (event === 'shorts.completed') {
    console.log(`Request ${requestId} completed with ${data.shorts.length} clips`);
    // Process the clips — download, publish, notify users, etc.
  } else if (event === 'shorts.failed') {
    console.log(`Request ${requestId} failed: ${data.failureReason}`);
  }
 
  res.sendStatus(200);
});
 
app.listen(3000);

Flask (Python)

from flask import Flask, request, jsonify
 
app = Flask(__name__)
 
@app.route("/webhook/ssemble", methods=["POST"])
def handle_webhook():
    payload = request.json
    event = payload["event"]
    request_id = payload["requestId"]
 
    if event == "shorts.completed":
        shorts = payload["data"]["shorts"]
        print(f"Request {request_id} completed with {len(shorts)} clips")
        # Process the clips
    elif event == "shorts.failed":
        reason = payload["data"]["failureReason"]
        print(f"Request {request_id} failed: {reason}")
 
    return jsonify({"ok": True}), 200

Using with automation platforms

Webhooks work natively with no-code automation tools:

n8n — Use the Webhook trigger node, or install the n8n-nodes-ssemble community node for a fully integrated experience
Zapier — Use the "Webhooks by Zapier" trigger to receive completion events
Make — Use the "Webhooks" module as a trigger in your scenario

No dedicated app or plugin is needed — just paste your automation platform's webhook URL as the webhookUrl parameter.

On this page