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.
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.
POST /openshorts HTTP/1.1
Content-Type: application/json
User-Agent: OpenShorts-Webhook/1.0
X-OpenShorts-Signature: sha256=<hex>{
"event": "job.completed",
"job_id": "2f6c0a1e-...",
"status": "completed",
"clips": [
{
"index": 0,
"title": "...",
"video_url": "https://your-host/videos/2f6c0a1e-.../FILE_NAME.mp4"
}
]
}{
"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.
| Field | Type | Meaning |
|---|---|---|
| event | String | job.completed, job.failed or job.cancelled. |
| job_id | String | Use it to call GET /api/status/{job_id} or to deduplicate. |
| status | String | completed, failed or cancelled. |
| clips[].index | Number | Clip position, starting at 0. |
| clips[].title | String | Clip title. |
| clips[].video_url | String | Clip link. Downloading the file needs the job owner's token. |
| error | String | A 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.
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 "", 204const 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.
Yes. event is job.cancelled, separate from job.failed, so your system does not resubmit a job the user stopped.
Call that URL with an Authorization: Bearer header for the job owner's account. Paths under /videos are closed to anonymous callers.
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




