Webhookok
A webhook URL konfigurálásával a szerverét értesítjük, amikor egy fájlfordítási munka (/jobs) befejeződik (sikeresen vagy nem). A POST /jobs/{id}/cancel-vel törölt munkák nem küldenek visszahívást. Dokumentumkezelési és médiamunkák esetén kérjék le az állapotukat saját lekérdezési végpontjaikon.
Webhookok kezelése
Szekció neve “Webhookok kezelése”Az API-n keresztül kezelhető, felhasználónként legfeljebb 3 darab:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deletePélda létrehozása:
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" }'Az URL elérhetőnek kell lennie a nyilvános internetről, lehetőleg HTTPS segítségével; a privát hálózatok, helyi címek és rosszul formált URL-ek esetén 400 érték jön vissza. A PATCH művelet megváltoztathatja a következőket: url, secret, events, description és status (active / disabled).
Visszahívási formátum
Szekció neve “Visszahívási formátum”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 }}Események
Szekció neve “Események”| Esemény | Amikor |
|---|---|
job.completed | A feladat véget ér; data.status completed vagy failed |
A sikertelen feladatok is a job.completed eseményt használják; különböztessük meg őket a data.status == "failed" és az opcionális data.error segítségével. A sikeres feladatok nem tartalmaznak error mezőt. A data.char_count a fordítás karaktereinek száma, a sikertelen feladatoknál a 0.
A events csak a job.completed és a * értékeket fogadja el (minden esemény); más értékek vagy az üres lista 422-es hibakódot eredményez. A PATCH-kérésekben hagyja ki azokat a mezőket, amelyeket nem módosít; a null küldése szintén 422-es hibakódot ad vissza.
Ellenőrizze az aláírást
Szekció neve “Ellenőrizze az aláírást”Amikor beállít egy secret -at a webhookra, minden visszahívás tartalmazza a X-Webhook-Signature -ot. Ellenőrizze ezt a HMAC-SHA256 segítségével az nyers kéréstesten :
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 eventAz aláírás kizárólag a testrészt érinti, a fejléceket nem. Az újrafelhasználási védelem érdekében ellenőrizze a timestamp értékét a testben, miután az aláírás sikeres (ez megegyezik a X-Webhook-Timestamp értékkel, de csak a test értéke van aláírva), és távolítsa el a duplikátumokat a data.job_id és data.status segítségével. Az újraküldések változatlanul küldik az első kézbesítés testrészeit, ugyanazzal a timestamp értékkel, és az utolsó újraküldés körülbelül 8,6 órával az első kézbesítés után történik, ezért ne tegye rövidebbre ezt az időablakot ennél (a példa 12 órát használ).
Szállítás
Szekció neve “Szállítás”- A fogadó félnek 15 másodpercen belül vissza kell küldenie a
2xx-et ahhoz, hogy a kézbesítés sikeresnek számítson; az átirányításokat nem követik. - A sikertelen kézbesítések (időtúllépés, kapcsolati hiba vagy nem
2xx) automatikusan újraküldésre kerülnek: az előző sikertelenség után 1 perc, 5 perc, 30 perc, 2 óra és 6 óra múlva, legfeljebb 6 kézbesítés eseményenként, ezt követően pedig már nem. - Az újrapróbálkozások a webhook aktuális URL-címére kerülnek, a testmező értéke változatlan marad (
timestamp,dataés az aláírás megegyezik az első kézbesítéssel; ha közben asecretmegváltozott, akkor az újsecretszignózza); a már kézbesített eseményeket nem küldik újra. - Amikor egy webhook letiltásra kerül, törölve lett vagy már nem iratkozott fel az eseményre, a függőben lévő újrapróbálkozásokat törlik.
- A fogadók az eseményeket
data.job_idésdata.statusszerint idempotensen kezeljék, és a biztonságos persistálás után gyorsan reagáljanak. - Egy fiók több webhookja párhuzamosan kerül kézbesítésre; egy lassú fogadó nem akadályozza a többit.
- 10 egymást követő sikertelen kézbesítés (újrapróbálkozásokkal együtt) után a webhook automatikusan letiltódik; kapcsolja be újra a
PATCHsegítségével, miután a fogadó rendbe jött. - A
GET /api/v1/webhooksmegjeleníti az egyes webhookok utolsó aktiválási idejét, állapotkódját és egymást követő hibaszámát.