Веб-қосылымдар
Webhook 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 }}Оқиғалар
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 “Жеткізу”- Қабылдаушы жеткізілім сәтті деп есептелуі үшін
2xxмәнін 15 секунд ішінде қайтаруы тиіс; бағыттаулар орындалмайды. - Сәтсіз жеткізулер (уақыт өтіп кету, байланыс қатесі немесе
2xxемес) автоматты түрде қайта тыңдалады: алдыңғы сәтсіздіктен кейін 1 минут, 5 минут, 30 минут, 2 сағат және 6 сағат, әр оқиғаға ең көбі 6 рет, одан кейін қайта тыңдау болмайды. - Қайта әрекеттер веб-қосымшаның ағымдағы URL мекенжайына денесі өзгермеген күйінде жіберіледі (
timestamp,dataжәне қолтаңба бірінші жеткізудегімен сәйкес келеді; егер арасындаsecretөзгерген болса, онда жаңаsecretқолтаңбасы қойылады); бұрын жеткізілген оқиғалар қайта жіберілмейді - Вебхук өшірілгенде, жойылғанда немесе оқиғаға тіркелмегенде, оның күтіп тұрған қайта тыңдаулары жойылады.
- Қабылдағыштар
data.job_idжәнеdata.statusарқылы оқиғаларды идемпотентті түрде өңдеп, оларды қауіпсіз сақтағаннан кейін жылдам жауап беруі керек. - Бір аккаунтқа тиесілі бірнеше веб-бұғаттау параллельді түрде жеткізіледі; баяу қабылдағыш басқалардың жұмысын баяулатпайды.
- Қатарынан 10 рет сәтсіз жеткізуден кейін (қайта тырысу да қоса есептеледі), вебхук автоматты түрде өшіріледі; алушыны түзеткеннен кейін
PATCHкөмегімен оны қайта іске қосыңыз GET /api/v1/webhooksәр веб-қосылымның соңғы іске қосылу уақытын, мәртебе кодын және қатарынан болған сәтсіздіктерді көрсетеді