Přeskočit na obsah

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.

Spravováno prostřednictvím rozhraní API, až 3 na uživatele:

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

Vytvořte příklad:

Terminál
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).

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
}
}
UdálostKdyž
job.completedPrá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.

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

  • Přijímač musí vrátit 2xx do 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, data a podpis odpovídá prvnímu doručení; pokud se mezitím secret změ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_id a data.status a 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/webhooks zobrazuje čas posledního spuštění, stavový kód a počet za sebou následujících selhání každého webhooku