跳转到内容

വെബ്ബുക്കുകൾ

ഒരു webhook 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"
}'

URL പൊതു ഇൻ്റർനെറ്റിൽ നിന്ന് എത്തിച്ചേരാവുന്നതായിരിക്കണം, വെയിലത്ത് HTTPS-ന് മുകളിൽ; സ്വകാര്യ നെറ്റ്‌വർക്കുകൾ, പ്രാദേശിക വിലാസങ്ങൾ, തെറ്റായ URL-കൾ എന്നിവ 400 നൽകുന്നു. പാച്ചിന് url, secret, events, description, status (active / disabled) എന്നിവ മാറ്റാനാകും.

കോൾബാക്ക് ഫോർമാറ്റ്

Section titled “കോൾബാക്ക് ഫോർമാറ്റ്”
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. ഒരു പാച്ചിൽ, നിങ്ങൾ മാറ്റാത്ത ഫീൽഡുകൾ ഉപേക്ഷിക്കുക; 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 കാണിക്കുന്നു