Nhận kết quả job mà không cần polling
Truyền webhook_url vào POST /api/process. Khi job kết thúc, VimeoClip POST kết quả tới URL đó. Thêm webhook_secret để xác minh body bằng HMAC-SHA256.
Điều kiện để webhook chạy
- webhook_url dùng http hoặc https và trỏ tới địa chỉ công khai. Localhost và IP mạng nội bộ bị từ chối, request trả 400 "Invalid webhook_url".
- Máy nhận trả mã 2xx trong 10 giây. Redirect được tính là thất bại.
- Job không chạy test_mode. Job test không gửi webhook.
- Muốn link clip trong payload là URL đầy đủ đúng địa chỉ công khai, đặt PUBLIC_API_URL trên máy chủ. Nếu không, VimeoClip dùng địa chỉ mà người gọi đã kết nối tới.
Đăng ký webhook cho một job
Webhook gắn với từng job, không có trang cấu hình chung. MCP nhận hai tham số cùng tên trong 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"
}'Máy nhận sẽ thấy gì
Body là JSON. event là job.completed, job.failed hoặc job.cancelled. Header chữ ký chỉ có khi job được tạo với 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": "..."
}Các field trong payload
Job không thành công có clips rỗng và thêm field error.
| Field | Kiểu | Ý nghĩa |
|---|---|---|
| event | Chuỗi | job.completed, job.failed hoặc job.cancelled. |
| job_id | Chuỗi | Dùng để gọi GET /api/status/{job_id} hoặc để chống xử lý trùng. |
| status | Chuỗi | completed, failed hoặc cancelled. |
| clips[].index | Số | Vị trí clip, bắt đầu từ 0. |
| clips[].title | Chuỗi | Tiêu đề clip. |
| clips[].video_url | Chuỗi | Link clip. Tải file cần token của chủ job. |
| error | Chuỗi | Lý do đã được làm sạch. Chỉ có khi job không thành công. |
Cần thêm điểm, mô tả từng nền tảng hoặc thời gian bắt đầu, kết thúc của clip? Gọi GET /api/status/{job_id} sau khi nhận webhook.
Xác minh chữ ký
Header có dạng sha256=<hex>, là HMAC-SHA256 của body với webhook_secret làm khoá. Luôn tính trên đúng các byte nhận được. Parse JSON rồi serialize lại sẽ cho chuỗi khác và chữ ký không khớp.
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():
# Giữ nguyên các byte VimeoClip đã ký, đừng serialize lại.
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);
}
// Giữ nguyên các byte VimeoClip đã ký, đừng serialize lại.
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);Cách VimeoClip gửi
Mỗi job được gửi một lần khi đạt trạng thái cuối. Nếu lần gửi thất bại, VimeoClip thử lại theo lịch cố định.
- Tối đa 3 lần: gửi ngay, chờ 10 giây rồi gửi lại, chờ thêm 60 giây rồi gửi lần cuối.
- Mỗi lần có timeout 10 giây. Mã 2xx là thành công. Mọi mã khác và mọi redirect tính là thất bại.
- Hết 3 lần thì dừng. Kết quả vẫn đọc được qua GET /api/status/{job_id}.
- URL được kiểm tra lúc tạo job và kiểm tra lại trước mỗi lần gửi. VimeoClip kết nối đúng địa chỉ IP vừa kiểm tra.
- Máy nhận nên xử lý trùng lặp theo job_id, vì một lần gửi có thể tới nơi dù phản hồi bị mất.
Câu hỏi thường gặp
VimeoClip chặn địa chỉ không công khai để webhook không thể bị dùng để gọi vào mạng nội bộ. Khi thử trên máy cá nhân, bạn cần một URL công khai trỏ về máy nhận.
Có. event là job.cancelled, tách riêng với job.failed để hệ thống của bạn không tự gửi lại một job người dùng đã dừng.
Gọi URL đó với header Authorization: Bearer của tài khoản chủ job. Đường dẫn /videos không mở cho người chưa đăng nhập.
Nối webhook vào n8n
Workflow mẫu đã có sẵn node nhận webhook và tách từng clip thành một item.
Video minh hoạ (stock), không phải kết quả của VimeoClip · Storyblocks




