Webhooks
Nakon što je konfigurirana URL adresa web-hooka, vaš server obavješćuje se kada zadatak prevoda datoteke (/jobs) završi (uspješno ili ne). Zadaci otkazani pomoću POST /jobs/{id}/cancel ne šalju povratnu pozivnicu. Za operacije s dokumentima i zadatke za medije, provjeravajte stanje putem njihovih vlastitih krajnjih točaka upita.
Upravljanje webhookovima
Section titled “Upravljanje webhookovima”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} deleteStvorite primjer:
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 nevaljali URL-ovi vraćaju 400. PATCH može promijeniti url, secret, events, description i status (active / disabled).
Format poziva natrag
Section titled “Format poziva natrag”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 | Posao završava; data.status je completed ili failed |
Neuspješni zadaci također koriste događaj job.completed; razlikujte ih prema data.status == "failed" i opcionalnom data.error. Uspješni zadaci nemaju polje error. data.char_count je broj znakova u prijevodu, a 0 za neuspjele zadatke.
events prihvaća samo job.completed i * (sve događaje); druga vrijednost ili prazna lista vraćaju 422. U PATCH-u izostavite polja koja ne mijenjate; slanje null također vraća 422.
Provjerite potpis
Section titled “Provjerite potpis”Kada postavite secret na webhook, svaki povratni poziv sadrži X-Webhook-Signature. Provjerite to pomoću HMAC-SHA256 preko /izvornog tijela zahtjeva :
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 tijelo, a ne zaglavlja. Za zaštitu od ponovnog reproduciranja provjerite timestamp u tijelu nakon što potpis prođe (jednako je X-Webhook-Timestamp, ali potpisuje se samo vrijednost tijela), te uklonite duplikate pomoću data.job_id i data.status. Ponavljanja šalju nepromijenjeno tijelo prve dostave s istim timestamp, a posljednje ponavljanje dolazi otprilike 8,6 sati nakon prve dostave, stoga ne skraćujte to razdoblje manje od tog vremena (primjer koristi 12 sati).
Dostava
Section titled “Dostava”- Primatelj mora vratiti
2xxunutar 15 sekundi kako bi isporuka bila uspješna; preusmjeravanja se ne slijede. - Neuspjele dostave (timeout, pogreška pri povezivanju ili ne-
2xx) automatski se ponavljaju: 1 minutu, 5 minuta, 30 minuta, 2 sata i 6 sati nakon prethodnog neuspjeha, najviše 6 dostava po događaju, zatim više ne - Ponovni pokušaji slanja idu na trenutnu URL adresu webhooka s neizmijenjenim tijelom (
timestamp,datai potpis odgovaraju prvom isporučivanju; ako sesecretpromijenio u međuvremenu, novisecretpotpisuje); događaji koji su već isporučeni ne šalju se ponovno - Kada se webhook deaktivira, izbriše ili više nije pretplaćen na događaj, njegovi čekajući pokušaji ponovnog pokretanja otkazuju se.
- Primatelji bi trebali obrađivati događaje idempotentno prema
data.job_ididata.statuste brzo odgovoriti nakon što ih sigurno pohrane. - Više webhookova jednog računa dostavljaju se paralelno; sporiji primatelj ne usporava ostale.
- Nakon 10 uzastopnih neuspješnih pokušaja dostave (uključujući ponovne pokušaje), webhook se automatski deaktivira; ponovno ga aktivirajte pomoću
PATCHnakon što se primatelj popravi. GET /api/v1/webhooksprikazuje vrijeme posljednjeg pokretanja svakog webhuka, statusni kod i uzastopne greške