वेबहुक्स
वेबहुक URL कॉन्फ़िगर होने पर, जब किसी फ़ाइल अनुवाद कार्य (/jobs) का समापन होता है (सफलतापूर्वक या असफलतापूर्वक), तो आपका सर्वर सूचित हो जाता है। POST /jobs/{id}/cancel द्वारा रद्द किए गए कार्यों के लिए कोई कॉलबैक नहीं भेजा जाता है। दस्तावेज़ संचालन और मीडिया कार्यों के लिए, उन्हें अपने स्वयं के क्वेरी एंडपॉइंट्स से पोल करना चाहिए।
वेबहुक्स प्रबंधित करें
Section titled “वेबहुक्स प्रबंधित करें”API के माध्यम से प्रबंधित, प्रति उपयोगकर्ता अधिकतम 3:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteउदाहरण बनाएं:
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" }'यूआरएल सार्वजनिक इंटरनेट से पहुँचा जा सकता होना चाहिए, अधिमानतः HTTPS के माध्यम से; निजी नेटवर्क, स्थानीय पते और गलत फ़ॉर्मेट वाले यूआरएल 400 लौटाते हैं। PATCH url, secret, events, description और status (active / disabled) को बदल सकता है।
कॉलबैक प्रारूप
Section titled “कॉलबैक प्रारूप”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 }}घटनाएँ
Section titled “घटनाएँ”| घटना | जब |
|---|---|
job.completed | एक जॉब समाप्त होता है; data.status completed या failed है |
विफल जॉब्स job.completed इवेंट का भी उपयोग करते हैं; उन्हें data.status == "failed" और वैकल्पिक data.error से पहचानें। सफल जॉब्स में कोई error फ़ील्ड नहीं होता। data.char_count अनुवाद में वर्णों की संख्या है, जबकि विफल जॉब्स के लिए 0 है।
events केवल job.completed और * (सभी घटनाएँ) स्वीकार करता है; अन्य मान या खाली सूची 422 लौटाती है। एक PATCH में, जिन फ़ील्डों को आप बदल नहीं रहे हैं, उन्हें छोड़ दें; null भेजने पर भी 422 लौटाया जाता है।
हस्ताक्षर की पुष्टि करें
Section titled “हस्ताक्षर की पुष्टि करें”जब आप वेबहुक पर secret सेट करते हैं, तो हर कॉलबैक X-Webhook-Signature ले जाता है। इसे रॉ रिक्वेस्ट बॉडी पर HMAC-SHA256 के साथ सत्यापित करें:
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 eventहस्ताक्षर केवल बॉडी को कवर करता है, हेडर्स को नहीं। रिप्ले सुरक्षा के लिए, हस्ताक्षर पास होने के बाद बॉडी में timestamp की जाँच करें (यह X-Webhook-Timestamp के बराबर है, लेकिन केवल बॉडी का मान हस्ताक्षरित होता है), और data.job_id तथा data.status द्वारा डुप्लिकेट को हटाएँ। रीट्रायल पहली डिलीवरी की बॉडी को बिना किसी बदलाव के, उसी timestamp के साथ फिर से भेजते हैं, और अंतिम रीट्रायल पहली डिलीवरी के लगभग 8.6 घंटे बाद आता है, इसलिए विंडो को इससे छोटा न बनाएँ (उदाहरण में 12 घंटे का उपयोग किया गया है)।
डिलीवरी
Section titled “डिलीवरी”- डिलीवरी को सफल मानने के लिए, रिसीवर को 15 सेकंड के भीतर
2xxवापस करना होगा; रीडायरेक्ट का अनुसरण नहीं किया जाता। - विफल डिलीवरी (टाइमआउट, कनेक्शन त्रुटि या
2xxके अलावा) स्वचालित रूप से पुनः प्रयास की जाती है: पिछली विफलता के बाद 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे और 6 घंटे, प्रति घटना अधिकतम 6 डिलीवरी, फिर अधिक नहीं। - पुनर्प्रयास वेबहुक के वर्तमान URL पर शरीर को बिना बदले भेजे जाते हैं (
timestamp,dataऔर हस्ताक्षर पहली डिलीवरी से मेल खाते हैं; यदि इस बीचsecretबदल गया है, तो नयाsecretहस्ताक्षर करता है); पहले से डिलीवर किए गए घटनाओं को दोबारा नहीं भेजा जाता है - जब कोई वेबहुक अक्षम किया जाता है, हटा दिया जाता है या उसकी घटना के लिए अब सदस्यता नहीं होती, तो उसके लंबित पुनः प्रयास रद्द कर दिए जाते हैं।
- रिसीवर्स को
data.job_idऔरdata.statusके अनुसार इवेंट्स को आइडम्पोटेंटली हैंडल करना चाहिए और उन्हें सुरक्षित रूप से पर्सिस्ट करने के बाद जल्दी से जल्दी प्रतिक्रिया देनी चाहिए। - एक खाते के कई वेबहुक को समानांतर में डिलीवर किया जाता है; धीमा प्राप्तकर्ता अन्य वेबहुक को रोकता नहीं है।
- लगातार 10 असफल डिलीवरी (पुनः प्रयास सहित) के बाद, वेबहुक स्वचालित रूप से अक्षम हो जाता है; प्राप्तकर्ता को ठीक करने के बाद
PATCHके साथ इसे फिर से सक्षम करें। GET /api/v1/webhooksप्रत्येक वेबहुक के अंतिम ट्रिगर समय, स्थिति कोड और लगातार विफलताओं को दर्शाता है।