跳转到内容

వెబ్‌హుక్‌లు

వెబ్‌హుక్ 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 ద్వారా; ప్రైవేట్ నెట్‌వర్క్‌లు, లోకల్ అడ్రసెస్‌లు మరియు తప్పుగా రూపొందించబడిన URLs 400ను తిరిగి ఇస్తాయి. PATCH 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 తిరిగి ఇస్తుంది. 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 గంటలను ఉపయోగిస్తుంది).

  • డెలివరీ విజయవంతమైనదిగా పరిగణించబడాలంటే, రిసీవర్ $ x $ ను అలాగే ఉంచి 15 సెకన్లలోపు 2xx ను తిరిగి పంపాలి; రీడైరెక్ట్‌లు ఫాలో అవ్వబడవు.
  • విఫల డెలివరీలు (టైమ్‌అవుట్, కనెక్షన్ లోపం లేదా 2xx కాకుండా) స్వయంచాలకంగా పునఃప్రయత్నించబడతాయి: మునుపటి వైఫల్యం తర్వాత 1 నిమిషం, 5 నిమిషాలు, 30 నిమిషాలు, 2 గంటలు మరియు 6 గంటలు, ఒక సంఘటనకు గరిష్టంగా 6 డెలివరీలు, ఆ తర్వాత మరిన్ని జరగవు
  • పునఃప్రయత్నాలు బాడీని మార్చకుండా వెబ్‌హుక్ యొక్క ప్రస్తుత URLకి వెళ్తాయి (timestamp, data మరియు సిగ్నేచర్ మొదటి డెలివరీతో సరిపోలుతుంది; secret మధ్యలో మారితే, కొత్త secret సంతకాలు చేస్తుంది); ఇప్పటికే డెలివరీ అయిన ఈవెంట్‌లు మళ్లీ పంపబడవు
  • వెబ్‌హుక్ నిలిపివేయబడినప్పుడు, తొలగించబడినప్పుడు లేదా ఇకపై సంఘటనకు సబ్‌స్క్రైబ్ చేయనప్పుడు, దాని పెండింగ్ రీట్రైల్స్ రద్దు చేయబడతాయి.
  • రిసీవర్‌లు data.job_id మరియు data.status ద్వారా ఈవెంట్‌లను ఇడెంపోటెంట్‌గా నిర్వహించాలి మరియు వాటిని సురక్షితంగా పొడిగించిన తర్వాత త్వరగా స్పందించాలి.
  • ఒక ఖాతాలోని బహుళ వెబ్‌హుక్‌లు సమాంతరంగా పంపబడతాయి; నెమ్మదిగా ఉన్న గ్రహీత ఇతర వెబ్‌హుక్‌లను నిలుపుకోదు.
  • 10 వరుసగా విఫలమైన డెలివరీల తర్వాత (పునఃప్రయత్నాలు కూడా), webhook స్వయంచాలకంగా నిలిపివేయబడుతుంది; రిసీవర్ సరిదిద్దబడిన తర్వాత PATCH ద్వారా దాన్ని తిరిగి ప్రారంభించండి
  • GET /api/v1/webhooks ప్రతి వెబ్‌హుక్ యొక్క చివరి ట్రిగ్గర్ సమయం, స్టేటస్ కోడ్ మరియు వరుస వైఫల్యాలను చూపుతుంది