वेबहुक्स
वेबहुक 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" }'URL सार्वजनिक इंटरनेटवरून प्रवेशयोग्य असणे आवश्यक आहे, शक्यतो HTTPS वर; खाजगी नेटवर्क, स्थानिक पत्ते आणि चुकीच्या स्वरूपाच्या URL मुळे 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 }}| घटना | जेव्हा |
|---|---|
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 तासांचा वापर केला आहे).
- डिलिव्हरी यशस्वी मानण्यासाठी रिसीव्हरने 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प्रत्येक वेबहुकचा शेवटचा ट्रिगर वेळ, स्थिती कोड आणि सलग अयशस्वीपणाचे दर्शवतो