Webhooks
Po nakonfigurovaní URL webhooku je váš server upozornený, keď sa dokončí úloha prekladu súboru (/jobs) (úspešne alebo neúspešne). Úlohy zrušené pomocou POST /jobs/{id}/cancel žiadny spätný volanie neodosielajú. Pre operácie s dokumentmi a médiámi požadujte aktualizáciu prostredníctvom ich vlastných koncových bodov dotazov.
Spravovať webové webhooky
Section titled “Spravovať webové webhooky”Spravované prostredníctvom rozhrania API, až 3 na používateľa:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteVytvorte príklad:
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 musí byť dostupný z verejného internetu, najlepšie cez HTTPS; súkromné siete, lokálne adresy a chybné URL vracajú 400. Príkaz PATCH môže zmeniť url, secret, events, description a status (active / disabled).
Formát callbacku
Section titled “Formát callbacku”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 }}Udalosti
Section titled “Udalosti”| Udialosť | Keď |
|---|---|
job.completed | Práca sa ukončí; data.status je completed alebo failed |
Neúspešné úlohy tiež používajú udalosť job.completed; rozlíšte ich podľa data.status == "failed" a voliteľnej data.error. Úspešné úlohy neobsahujú žiadne pole error. data.char_count je počet znakov v preklade, 0 pre neúspešné úlohy.
events akceptuje iba job.completed a * (všetky udalosti); iné hodnoty alebo prázdny zoznam vrátia 422. Pri operácii PATCH neuvádzajte polia, ktoré nemeníte; odoslanie null tiež vráti 422.
Overte podpis
Section titled “Overte podpis”Keď nastavíte secret na webhook, každý callback prenáša X-Webhook-Signature. Overte si to pomocou HMAC-SHA256 cez /neupravené telo požiadavky :
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 eventPodpis pokrýva iba telo správy, nie hlavičky. Pre ochranu proti opakovanému odosielaniu skontrolujte timestamp v tele správy po úspešnom overení podpisu (má rovnakú hodnotu ako X-Webhook-Timestamp, ale podpisuje sa iba hodnota tela), a eliminujte duplikáty pomocou data.job_id a data.status. Pri opakovaných pokusoch sa telo prvého doručenia odosiela bez zmien s rovnakým timestamp, pričom posledný opakovaný pokus nasleduje približne 8,6 hodiny po prvom doručení, preto neustupujte od tejto doby (v príklade je použitých 12 hodín).
Dodávka
Section titled “Dodávka”- Prijímač musí vrátiť
2xxdo 15 sekúnd, aby bola doručenie považované za úspešné; presmerovania sa nevykonávajú. - Neúspešné doručenia (časový limit, chyba pripojenia alebo ne-
2xx) sa automaticky opakujú: 1 minúta, 5 minút, 30 minút, 2 hodiny a 6 hodín po predchádzajúcom neúspechu, maximálne 6 doručení za udalosť, potom už žiadne ďalšie. - Opakované pokusy o odoslanie smerujú na aktuálnu URL webhooku so zachovaným telom (
timestamp,dataa podpis zodpovedá prvému doručeniu; ak sa medzi tým zmenilsecret, podpisuje sa novýsecret); udalosti, ktoré už boli doručené, nie sú odosielané opätovne. - Keď je webhook zakázaný, odstránený alebo už nie je prihlásený k udalosti, jeho čakajúce opakované pokusy sú zrušené.
- Prijímače by mali spracovávať udalosti idempotentne podľa
data.job_idadata.statusa rýchlo reagovať po ich bezpečnom uložení. - Viacero webových webhooks z jedného účtu sú doručované paralelne; pomalý prijímač nezpomalí ostatné.
- Po 10 po sebe nasledujúcich neúspešných doručeniach (vrátane opakovaných pokusov) sa webhook automaticky deaktivuje; aktivujte ho znova pomocou
PATCH, akonáhle je prijímač opravený. GET /api/v1/webhookszobrazuje posledný čas spustenia každého webhooku, kód stavu a počet za sebou nasledujúcich chýb