Vebhuki
Kada je konfigurisana vebhuk URL adresa, vaš server se obaveštava kada se završi zadatak prevoda datoteke (/jobs) (uspešno ili ne). Zadaci otkazane pomoću POST /jobs/{id}/cancel ne šalju povratnu poziv. Za operacije sa dokumentima i medijske zadatke, proveravajte stanje putem sopstvenih endpointova za upit.
Upravljanje vebhukovima
Section titled “Upravljanje vebhukovima”Upravlja se putem API-ja, do 3 po korisniku:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteKreirajte primer:
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 mora biti dostupan iz javnog interneta, po mogućnosti preko HTTPS; privatne mreže, lokalne adrese i pogrešno formirane URL-ove vraćaju 400. PATCH može da promeni url, secret, events, description i status (active / disabled).
Format povratne pozive
Section titled “Format povratne pozive”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 }}Događaji
Section titled “Događaji”| Događaj | Kada |
|---|---|
job.completed | Rad se završava; data.status je completed ili failed |
Neuspešni zadaci takođe koriste događaj job.completed; razlikujte ih pomoću data.status == "failed" i opcionalnog data.error. Uspešni zadaci nemaju polje error. data.char_count je broj karaktera u prevodu, a 0 za neuspešne zadatke.
events prihvata samo job.completed i * (sve događaje); druge vrednosti ili prazna lista vraćaju 422. U PATCH zahtevu, izostavite polja koja ne menjate; slanje null takođe vraća 422.
Proverite potpis
Section titled “Proverite potpis”Kada postavite secret na vebhuk, svaki povratni poziv nosi X-Webhook-Signature. Proverite to pomoću HMAC-SHA256 preko /sirovog tela zahteva :
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 eventPotpis pokriva samo telo, a ne zaglavlja. Za zaštitu od ponovnog puštanja, proverite timestamp u telu nakon što potpis prođe (jednako je X-Webhook-Timestamp, ali se potpisuje samo vrednost tela), i duplikate uklonite pomoću data.job_id i data.status. Ponovljeni pokušaji šalju netaknuto telo prve dostave, sa istim timestamp, a poslednji ponovljeni pokušaj dolazi oko 8.6 sati nakon prve dostave, pa ne skraćujte to vreme manje od toga (u primeru se koristi 12 sati).
Isporuka
Section titled “Isporuka”- Prijemnik mora da vrati
2xxu roku od 15 sekundi kako bi isporuka bila uspešna; preusmeravanja se ne prate. - Neuspešne isporuke (vremenski ograničenja, greška u vezi ili ne-
2xx) se automatski ponavljaju: 1 minut, 5 minuta, 30 minuta, 2 časa i 6 časova nakon prethodnog neuspeha, najviše 6 isporuka po događaju, zatim bez daljeg ponavljanja. - Ponovljeni pokušaji se šalju na trenutnu URL vebhuka uz nepromenjeno telo poruke (
timestamp,datai potpis odgovara prvoj isporuci; ako se između toga promenilosecret, novosecretje korišćeno za potpisivanje); događaji koji su već isporučeni ne šalju se ponovo - Kada je vebhuk onemogućen, izbrisan ili više nije pretplaćen na događaj, njegovi očekivani ponovni pokušaji se otkazuju.
- Prijemnici treba da obrađuju događaje idempotentno prema
data.job_ididata.status, i brzo reaguju nakon što ih bezbedno sačuvaju. - Više vebhukova jednog naloga dostavljaju se paralelno; spor prijemnik ne usporava ostale.
- Nakon 10 uzastopnih neuspešnih isporuka (uključujući ponovne pokušaje), vebhuk se automatski onemogućava; ponovo ga omogućite pomoću
PATCHkada se primalac popravi. GET /api/v1/webhooksprikazuje vreme poslednjeg pokretanja svakog vebhuka, statusni kod i broj uzastopnih neuspeha