Đến nội dung chính
[ Webhook ]

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.

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"
  }'

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.

Header · 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": "..."
}

Các field trong payload

Job không thành công có clips rỗng và thêm field error.

FieldKiểuÝ nghĩa
eventChuỗijob.completed, job.failed hoặc job.cancelled.
job_idChuỗiDùng để gọi GET /api/status/{job_id} hoặc để chống xử lý trùng.
statusChuỗicompleted, failed hoặc cancelled.
clips[].indexSốVị trí clip, bắt đầu từ 0.
clips[].titleChuỗiTiêu đề clip.
clips[].video_urlChuỗiLink clip. Tải file cần token của chủ job.
errorChuỗiLý 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.

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():
    # 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 "", 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);
}

// 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.

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