इसे छोड़कर कंटेंट पर जाएं

वेबहुक्स

वेबहुक URL कॉन्फ़िगर होने पर, जब किसी फ़ाइल अनुवाद कार्य (/jobs) का समापन होता है (सफलतापूर्वक या असफलतापूर्वक), तो आपका सर्वर सूचित हो जाता है। POST /jobs/{id}/cancel द्वारा रद्द किए गए कार्यों के लिए कोई कॉलबैक नहीं भेजा जाता है। दस्तावेज़ संचालन और मीडिया कार्यों के लिए, उन्हें अपने स्वयं के क्वेरी एंडपॉइंट्स से पोल करना चाहिए।

वेबहुक्स प्रबंधित करें

Section titled “वेबहुक्स प्रबंधित करें”

API के माध्यम से प्रबंधित, प्रति उपयोगकर्ता अधिकतम 3:

POST /api/v1/webhooks create
GET /api/v1/webhooks list
PATCH /api/v1/webhooks/{id} update / disable
DELETE /api/v1/webhooks/{id} delete

उदाहरण बनाएं:

Terminal window
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) को बदल सकता है।

POST your-webhook-url
Content-Type: application/json
X-Webhook-Event: job.completed
X-Webhook-Timestamp: 1782900150
X-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 hashlib
import hmac
import json
import 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 प्रत्येक वेबहुक के अंतिम ट्रिगर समय, स्थिति कोड और लगातार विफलताओं को दर्शाता है।