Webhooks
Po nakonfigurování URL webhooku je váš server upozorněn, když skončí úloha překladu souboru (/jobs) – ať už úspěšně, nebo ne. Úlohy zrušené pomocí POST /jobs/{id}/cancel žádný callback neodesílají. U operací s dokumenty a multimediálních úloh se vyhledávají vlastní dotazovací koncové body.
Spravovat webové připojení
Section titled “Spravovat webové připojení”Spravováno prostřednictvím rozhraní API, až 3 na uživatele:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteVytvořte pří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í být dostupná z veřejného internetu, nejlépe přes HTTPS; soukromé sítě, místní adresy a chybně formátované URL vracejí 400. Příkaz PATCH může změnit 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 }}Události
Section titled “Události”| Událost | Když |
|---|---|
job.completed | Práce končí; data.status je completed nebo failed |
Nevydařené úlohy také používají událost job.completed; rozlišujte je podle data.status == "failed" a volitelného data.error. Úspěšné úlohy neobsahují pole error. data.char_count je počet znaků v překladu, 0 pro nevydařené úlohy.
events akceptuje pouze job.completed a * (všechny události); jiné hodnoty nebo prázdný seznam vracejí 422. Při PATCH zanechte pole, která neměníte; odeslání null také vrátí 422.
Ověřte podpis
Section titled “Ověřte podpis”Když nastavíte secret na webhooku, každý callback přenáší X-Webhook-Signature. Ověřte to pomocí HMAC-SHA256 přes /nezpracované tělo požadavku :
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ývá pouze tělo zprávy, nikoli záhlaví. Pro ochranu proti opakovanému přenosu zkontrolujte timestamp v těle zprávy poté, co podpis prošel (je totožné s X-Webhook-Timestamp, ale podepsána je pouze hodnota těla), a odstranění duplicity provedete pomocí data.job_id a data.status. Při opakovaných pokusech se odešle nezměněné tělo první doručené zprávy se stejným timestamp, přičemž poslední opakovaný pokus následuje přibližně 8,6 hodiny po prvním doručení, proto okno neprodlužujte méně než na tuto dobu (v příkladu je použito 12 hodin).
Dodání
Section titled “Dodání”- Přijímač musí vrátit
2xxdo 15 sekund, aby bylo doručení považováno za úspěšné; přesměrování se nevyhodnocují. - Nevydařené doručení (časový limit, chyba připojení nebo kód
2xx) jsou automaticky opakovány: 1 minuta, 5 minut, 30 minut, 2 hodiny a 6 hodin po předchozím selhání, maximálně 6 pokusů na událost, poté již žádné další - Opakované pokusy odesílají data na aktuální URL webhooku s nezměněným tělem (
timestamp,dataa podpis odpovídá prvnímu doručení; pokud se mezitímsecretzměnil, podepisuje novýsecret); události, které již byly doručeny, nejsou odesílány znovu. - Když je webhook deaktivován, smazán nebo již není přihlášen k události, jeho čekající opakované pokusy jsou zrušeny.
- Přijímače by měly zpracovávat události idempotentně podle
data.job_idadata.statusa po jejich bezpečném uložení rychle reagovat. - Více webhooků z jednoho účtu jsou doručovány paralelně; pomalý přijímač nezpomaluje ostatní.
- Po 10 po sobě jdoucích neúspěšných doručeních (včetně opakovaných pokusů) je webhook automaticky deaktivován; aktivujte jej znovu pomocí
PATCH, jakmile bude přijímač opraven. GET /api/v1/webhookszobrazuje čas posledního spuštění, stavový kód a počet za sebou následujících selhání každého webhooku