Skip to main content
[ Webhooks ]

Get job results without polling

Pass webhook_url to POST /api/process. When the job ends, VimeoClip POSTs the result to that URL. Add webhook_secret to verify the body with HMAC-SHA256.

What a webhook needs

  • webhook_url uses http or https and points at a public address. Localhost and private network IPs are refused, and the request returns 400 "Invalid webhook_url".
  • The receiver answers 2xx within 10 seconds. A redirect counts as a failure.
  • The job is not a test_mode job. Test jobs send no webhook.
  • For clip links with your public address, set PUBLIC_API_URL on the server. Otherwise VimeoClip uses the address the caller connected to.

Register a webhook for a job

A webhook belongs to one job, and there is no global setting. MCP takes the same two arguments on process_video.

Request · bash
curl -s -X POST "$BASE/api/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "acknowledged": true,
    "webhook_url": "https://hooks.example.com/openshorts",
    "webhook_secret": "change-me"
  }'

What the receiver sees

The body is JSON. event is job.completed, job.failed or job.cancelled. The signature header is only there when the job was created with webhook_secret.

Headers · http
POST /openshorts HTTP/1.1
Content-Type: application/json
User-Agent: OpenShorts-Webhook/1.0
X-OpenShorts-Signature: sha256=<hex>
job.completed · json
{
  "event": "job.completed",
  "job_id": "2f6c0a1e-...",
  "status": "completed",
  "clips": [
    {
      "index": 0,
      "title": "...",
      "video_url": "https://your-host/videos/2f6c0a1e-.../FILE_NAME.mp4"
    }
  ]
}
job.failed · json
{
  "event": "job.failed",
  "job_id": "2f6c0a1e-...",
  "status": "failed",
  "clips": [],
  "error": "..."
}

Payload fields

A job that did not succeed has empty clips and an extra error field.

FieldTypeMeaning
eventStringjob.completed, job.failed or job.cancelled.
job_idStringUse it to call GET /api/status/{job_id} or to deduplicate.
statusStringcompleted, failed or cancelled.
clips[].indexNumberClip position, starting at 0.
clips[].titleStringClip title.
clips[].video_urlStringClip link. Downloading the file needs the job owner's token.
errorStringA scrubbed reason. Only present when the job did not succeed.

Need scores, per-platform descriptions or clip start and end times? Call GET /api/status/{job_id} after the webhook arrives.

Verify the signature

The header reads sha256=<hex>, the HMAC-SHA256 of the body keyed with webhook_secret. Always compute it over the exact bytes you received. Parsing the JSON and serializing it again gives a different string and the signature will not match.

Python · python
import hashlib
import hmac

from flask import Flask, abort, request

SECRET = "change-me"
app = Flask(__name__)


def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")


@app.post("/openshorts")
def openshorts_webhook():
    # Keep the exact bytes VimeoClip signed, and do not re-serialize.
    if not verify(request.get_data(), request.headers.get("X-OpenShorts-Signature"), SECRET):
        abort(401)
    event = request.get_json()
    print(event["event"], event["job_id"])
    return "", 204
Node · javascript
const crypto = require('crypto');
const express = require('express');

const SECRET = 'change-me';
const app = express();

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Keep the exact bytes VimeoClip signed, and do not re-serialize.
app.post('/openshorts', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('X-OpenShorts-Signature'), SECRET)) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  console.log(event.event, event.job_id);
  res.sendStatus(204);
});

app.listen(3000);

How VimeoClip delivers

Each job is sent once when it reaches a final state. If a delivery fails, VimeoClip retries on a fixed schedule.

  • Up to 3 attempts: right away, again after 10 seconds, and a last one 60 seconds after that.
  • Each attempt has a 10 second timeout. A 2xx code is a success. Any other code and any redirect is a failure.
  • After 3 attempts it stops. The result stays readable through GET /api/status/{job_id}.
  • The URL is checked when the job is created and again before every attempt. VimeoClip connects to the exact IP it just checked.
  • The receiver should deduplicate by job_id, because a delivery can arrive even when its response is lost.

Frequently asked questions

VimeoClip blocks non-public addresses so a webhook cannot be used to reach into a private network. When testing on a personal machine, you need a public URL that points at the receiver.

Plug the webhook into n8n

The template already has a webhook node and splits each clip into its own item.

Illustration (stock video), not VimeoClip output · Storyblocks