Webhooks
Dengan URL webhook yang dikonfigurasi, server Anda akan diberi tahu ketika pekerjaan penerjemahan file (/jobs) selesai (baik berhasil maupun tidak). Pekerjaan yang dibatalkan dengan POST /jobs/{id}/cancel tidak mengirimkan callback. Untuk operasi dokumen dan pekerjaan media, lakukan polling pada endpoint kueri masing-masing.
Kelola webhook
Section titled “Kelola webhook”Dikelola melalui API, hingga 3 per pengguna:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteBuat contoh:
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 harus dapat diakses dari internet publik, sebaiknya melalui HTTPS; jaringan pribadi, alamat lokal, dan URL yang tidak valid akan menghasilkan kesalahan 400. Metode PATCH dapat mengubah url, secret, events, description, dan status (active / disabled).
Format panggilan balik
Section titled “Format panggilan balik”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 }}Peristiwa
Section titled “Peristiwa”| Peristiwa | Ketika |
|---|---|
job.completed | Sebuah pekerjaan berakhir; data.status adalah completed atau failed |
Pekerjaan yang gagal juga menggunakan peristiwa job.completed; bedakan keduanya berdasarkan data.status == "failed" dan data.error yang bersifat opsional. Pekerjaan yang berhasil tidak menyertakan bidang error. data.char_count adalah jumlah karakter dalam terjemahan, sedangkan 0 untuk pekerjaan yang gagal.
events hanya menerima job.completed dan * (semua peristiwa); nilai lain atau daftar kosong menghasilkan kode kesalahan 422. Pada permintaan PATCH, biarkan bidang yang tidak diubah tanpa disertakan; pengiriman null juga akan menghasilkan kode kesalahan 422.
Verifikasi tanda tangan
Section titled “Verifikasi tanda tangan”Saat Anda menetapkan secret pada webhook, setiap panggilan balik membawa X-Webhook-Signature. Verifikasi dengan HMAC-SHA256 melalui badan permintaan mentah :
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 eventTanda tangan hanya mencakup badan pesan, bukan header. Untuk perlindungan replay, periksa timestamp pada badan pesan setelah tanda tangan lolos (nilainya sama dengan X-Webhook-Timestamp, tetapi hanya nilai badan yang ditandatangani), dan lakukan deduplikasi menggunakan data.job_id dan data.status. Pengulangan mengirim ulang badan pesan dari pengiriman pertama tanpa perubahan, dengan nilai timestamp yang sama, dan pengulangan terakhir dilakukan sekitar 8,6 jam setelah pengiriman pertama, sehingga jangan memperpendek jendela waktu lebih dari itu (contoh ini menggunakan 12 jam).
Pengiriman
Section titled “Pengiriman”- Penerima harus mengembalikan
2xxdalam waktu 15 detik agar pengiriman dianggap berhasil; pengalihan tidak diikuti - Pengiriman yang gagal (waktu habis, kesalahan koneksi, atau non-
2xx) akan dicoba ulang secara otomatis: 1 menit, 5 menit, 30 menit, 2 jam, dan 6 jam setelah kegagalan sebelumnya, maksimal 6 kali pengiriman per kejadian, kemudian tidak ada lagi. - Percobaan ulang dikirim ke URL webhook saat ini dengan body yang tidak diubah (
timestamp,data, dan tanda tangan sama dengan pengiriman pertama; jikasecretberubah di antaranya, makasecretyang baru digunakan untuk penandatanganan); peristiwa yang sudah dikirim tidak dikirimkan lagi - Ketika webhook dinonaktifkan, dihapus, atau tidak lagi berlangganan ke peristiwa tersebut, pengulangan yang tertunda akan dibatalkan.
- Penerima harus menangani peristiwa secara idempoten sesuai dengan
data.job_iddandata.status, serta merespons dengan cepat setelah menyimpannya dengan aman. - Beberapa webhook dari satu akun dikirim secara paralel; penerima yang lambat tidak menghambat yang lainnya
- Setelah 10 kali pengiriman gagal berturut-turut (termasuk upaya ulang), webhook dinonaktifkan secara otomatis; aktifkan kembali dengan
PATCHsetelah penerima diperbaiki GET /api/v1/webhooksmenampilkan waktu pemicu terakhir, kode status, dan jumlah kegagalan berturut-turut untuk setiap webhook