Skip to content

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.

Managed through the API, up to 3 per user:

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

Create example:

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

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
}
}
EventWhen
job.completedA 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.

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

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

  • The receiver must return 2xx within 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, data and the signature match the first delivery; if the secret changed in between, the new secret signs); 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_id and data.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 PATCH once the receiver is fixed
  • GET /api/v1/webhooks shows each webhook’s last trigger time, status code and consecutive failures