Preskočiť na obsah

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.

Spravované prostredníctvom rozhrania API, až 3 na používateľa:

POST /api/v1/webhooks create
GET /api/v1/webhooks list
PATCH /api/v1/webhooks/{id} update / disable
DELETE /api/v1/webhooks/{id} delete

Vytvorte príklad:

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 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).

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
}
}
UdialosťKeď
job.completedPrá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.

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 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

Podpis 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).

  • Prijímač musí vrátiť 2xx do 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, data a podpis zodpovedá prvému doručeniu; ak sa medzi tým zmenil secret, 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_id a data.status a 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/webhooks zobrazuje posledný čas spustenia každého webhooku, kód stavu a počet za sebou nasledujúcich chýb