跳转到内容

Веб-қосылымдар

Webhook URL-ы орнатылғаннан кейін, файлды аудару жұмысы (/jobs) аяқталғанда (сәтті немесе сәтсіз) серверіңізге хабарлама жіберіледі. POST /jobs/{id}/cancel кодымен тоқтатылған жұмыстар қайтару функциясын жібермейді. Құжаттық операциялар мен медиа жұмыстар үшін өздерінің сұраным нүктелеріне сұрау жіберіңіз.

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 қатесін береді. 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 қатесін қайтарады.

Вебхукқа 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 сағат қолданылады).

  • Қабылдаушы жеткізілім сәтті деп есептелуі үшін 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 әр веб-қосылымның соңғы іске қосылу уақытын, мәртебе кодын және қатарынан болған сәтсіздіктерді көрсетеді