Tovább a tartalomhoz

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.

Az API-n keresztül kezelhető, felhasználónként legfeljebb 3 darab:

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

Példa létrehozása:

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"
}'

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

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
}
}
EseményAmikor
job.completedA 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.

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

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

  • 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 a secret megváltozott, akkor az új secret szignó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 és data.status szerint 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 PATCH segítségével, miután a fogadó rendbe jött.
  • A GET /api/v1/webhooks megjeleníti az egyes webhookok utolsó aktiválási idejét, állapotkódját és egymást követő hibaszámát.