Webhooks
With a webhook URL configured, your server is notified when a file translation job (/jobs) ends (successfully or not). Jobs cancelled with POST /jobs/{id}/cancel send no callback. For document operations and media jobs, poll their own query endpoints.
Manage webhooks
Section titled “Manage webhooks”Managed through the API, up to 3 per user:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteCreate example:
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" }'The URL must be reachable from the public internet, preferably over HTTPS; private networks, local addresses and malformed URLs return 400. PATCH can change url, secret, events, description and status (active / disabled).
Callback format
Section titled “Callback format”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 }}Events
Section titled “Events”| Event | When |
|---|---|
job.completed | A job ends; data.status is completed or failed |
Failed jobs also use the job.completed event; tell them apart by data.status == "failed" and the optional data.error. Successful jobs carry no error field. data.char_count is the number of characters in the translation, 0 for failed jobs.
events accepts only job.completed and * (all events); other values or an empty list return 422. In a PATCH, leave out the fields you do not change; sending null also returns 422.
Verify the signature
Section titled “Verify the signature”When you set a secret on the webhook, every callback carries X-Webhook-Signature. Verify it with HMAC-SHA256 over the raw request body:
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 eventThe signature covers the body only, not the headers. For replay protection, check timestamp in the body after the signature passes (it equals X-Webhook-Timestamp, but only the body value is signed), and de-duplicate by data.job_id and data.status. Retries resend the first delivery’s body unchanged, with the same timestamp, and the last retry comes about 8.6 hours after the first delivery, so do not make the window shorter than that (the example uses 12 hours).
Delivery
Section titled “Delivery”- The receiver must return
2xxwithin 15 seconds for a delivery to count as successful; redirects are not followed - Failed deliveries (timeout, connection error or non-
2xx) are retried automatically: 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours after the previous failure, at most 6 deliveries per event, then no more - Retries go to the webhook’s current URL with the body unchanged (
timestamp,dataand the signature match the first delivery; if thesecretchanged in between, the newsecretsigns); events already delivered are not sent again - When a webhook is disabled, deleted or no longer subscribed to the event, its pending retries are cancelled
- Receivers should handle events idempotently by
data.job_idanddata.status, and respond quickly after persisting them safely - Multiple webhooks of one account are delivered in parallel; a slow receiver does not hold up the others
- After 10 consecutive failed deliveries (retries included), the webhook is disabled automatically; re-enable it with
PATCHonce the receiver is fixed GET /api/v1/webhooksshows each webhook’s last trigger time, status code and consecutive failures