Webhooks
Khi đã cấu hình URL webhook, máy chủ của bạn sẽ được thông báo khi một tác vụ dịch tệp (/jobs) kết thúc (thành công hay không). Các tác vụ bị hủy bằng POST /jobs/{id}/cancel sẽ không gửi phản hồi. Đối với các thao tác tài liệu và tác vụ phương tiện, hãy truy vấn các điểm cuối truy vấn riêng của chúng.
Quản lý webhook
Phần tiêu đề “Quản lý webhook”Được quản lý thông qua API, tối đa 3 cho mỗi người dùng:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteTạo ví dụ:
curl -X POST https://omnidoc.top/api/v1/webhooks \ -H "X-API-Key: sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/omnidoc", "secret": "your-signing-secret", "events": ["job.completed"], "description": "Production callback" }'URL phải có thể truy cập được từ internet công cộng, tốt nhất là qua HTTPS; mạng riêng, địa chỉ cục bộ và URL không hợp lệ sẽ trả về 400. Lệnh PATCH có thể thay đổi url, secret, events, description và status (active / disabled).
Định dạng callback
Phần tiêu đề “Định dạng callback”POST your-webhook-urlContent-Type: application/jsonX-Webhook-Event: job.completedX-Webhook-Timestamp: 1782900150X-Webhook-Signature: sha256=...{ "event": "job.completed", "timestamp": 1782900150, "data": { "job_id": "q3f8s6c2a9m1k4tx", "status": "completed", "file_name": "report.docx", "char_count": 12840 }}Sự kiện
Phần tiêu đề “Sự kiện”| Sự kiện | Khi |
|---|---|
job.completed | Một công việc kết thúc; data.status là completed hoặc failed |
Các công việc thất bại cũng sử dụng sự kiện job.completed; phân biệt chúng bằng data.status == "failed" và data.error tùy chọn. Các công việc thành công không có trường error. data.char_count là số ký tự trong bản dịch, còn 0 dành cho các công việc thất bại.
events chỉ chấp nhận job.completed và * (tất cả các sự kiện); các giá trị khác hoặc danh sách rỗng trả về lỗi 422. Trong yêu cầu PATCH, hãy bỏ qua các trường không thay đổi; việc gửi null cũng trả về lỗi 422.
Xác minh chữ ký
Phần tiêu đề “Xác minh chữ ký”Khi bạn thiết lập một secret trên webhook, mỗi callback đều chứa X-Webhook-Signature. Hãy xác minh điều này bằng HMAC-SHA256 thông qua raw request body :
import hashlibimport hmacimport jsonimport time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict: if not verify_webhook(payload, signature, secret): raise ValueError("invalid signature") event = json.loads(payload) if abs(time.time() - event["timestamp"]) > tolerance: raise ValueError("stale event") return eventChữ ký chỉ bao phủ phần thân, không bao gồm các tiêu đề. Để bảo vệ chống tái phát lại, hãy kiểm tra timestamp trong phần thân sau khi chữ ký được xác nhận (nó bằng X-Webhook-Timestamp, nhưng chỉ giá trị của phần thân được ký), và loại bỏ trùng lặp bằng data.job_id và data.status. Các lần gửi lại sẽ gửi lại nguyên trạng phần thân của lần gửi đầu tiên, với cùng giá trị timestamp, và lần gửi lại cuối cùng diễn ra khoảng 8,6 giờ sau lần gửi đầu tiên, vì vậy không được đặt khoảng thời gian ngắn hơn mức đó (ví dụ sử dụng 12 giờ).
Giao hàng
Phần tiêu đề “Giao hàng”- Người nhận phải trả về
2xxtrong vòng 15 giây để giao hàng được tính là thành công; các chuyển hướng sẽ không được theo dõi. - Các lần giao hàng thất bại (bị timeout, lỗi kết nối hoặc không phải
2xx) sẽ được tự động thử lại: sau 1 phút, 5 phút, 30 phút, 2 giờ và 6 giờ kể từ lần thất bại trước đó; tối đa 6 lần giao hàng cho mỗi sự cố, sau đó sẽ không thử lại nữa. - Các lần gửi lại được gửi đến URL hiện tại của webhook với nội dung không thay đổi (
timestamp,datavà chữ ký khớp với lần gửi đầu tiên; nếusecretđã thay đổi trong khoảng thời gian đó, thìsecretmới sẽ được sử dụng để ký); các sự kiện đã được gửi trước đó sẽ không được gửi lại. - Khi một webhook bị vô hiệu hóa, xóa hoặc không còn đăng ký sự kiện, các lần thử lại đang chờ xử lý của nó sẽ bị hủy.
- Các bộ thu nên xử lý các sự kiện một cách idempotent theo
data.job_idvàdata.status, đồng thời phản hồi nhanh chóng sau khi đã lưu chúng một cách an toàn. - Nhiều webhook của một tài khoản được gửi đồng thời; máy nhận chậm không làm chậm các webhook khác.
- Sau 10 lần giao hàng liên tiếp thất bại (bao gồm cả các lần thử lại), webhook sẽ tự động bị vô hiệu hóa; hãy kích hoạt lại bằng
PATCHkhi bên nhận đã được khắc phục. GET /api/v1/webhookshiển thị thời gian kích hoạt gần nhất, mã trạng thái và số lần thất bại liên tiếp của mỗi webhook