Webhooks
Con un URL webhook configurato, il tuo server viene notificato quando un job di traduzione file (/jobs) termina (con esito positivo o negativo). I job annullati con POST /jobs/{id}/cancel non inviano alcun callback. Per le operazioni sui documenti e i job multimediali, consulta i relativi endpoint di query.
Gestisci i webhook
Sezione intitolata “Gestisci i webhook”Gestibili tramite API, fino a 3 per utente:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteCrea esempio:
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" }'L’URL deve essere raggiungibile da Internet pubblico, preferibilmente tramite HTTPS; reti private, indirizzi locali e URL malformati restituiscono 400. Il metodo PATCH può modificare url, secret, events, description e status (active / disabled).
Formato del callback
Sezione intitolata “Formato del callback”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 }}| Evento | Quando |
|---|---|
job.completed | Un lavoro termina; data.status è completed o failed |
I lavori non riusciti utilizzano anch’essi l’evento job.completed; distinguerli tramite data.status == "failed" e l’opzionale data.error. I lavori riusciti non contengono alcun campo error. data.char_count indica il numero di caratteri nella traduzione, 0 per i lavori non riusciti.
events accetta solo job.completed e * (tutti gli eventi); altri valori o un elenco vuoto restituiscono 422. In una PATCH, ometti i campi che non modifichi; l’invio di null restituisce anch’esso 422.
Verifica la firma
Sezione intitolata “Verifica la firma”Quando imposti un secret sul webhook, ogni callback trasmette X-Webhook-Signature. Verificalo con HMAC-SHA256 tramite il corpo della richiesta grezza :
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 eventLa firma copre solo il corpo, non le intestazioni. Per la protezione contro i replay, verificare timestamp nel corpo dopo che la firma è stata accettata (corrisponde a X-Webhook-Timestamp, ma viene firmato solo il valore del corpo) e deduplicare tramite data.job_id e data.status. I tentativi di ritrasmissione inviano il corpo della prima consegna invariato, con lo stesso timestamp, e l’ultimo tentativo avviene circa 8,6 ore dopo la prima consegna; pertanto, non ridurre questa finestra temporale al di sotto di tale intervallo (nell’esempio si utilizzano 12 ore).
Consegna
Sezione intitolata “Consegna”- Il destinatario deve restituire
2xxentro 15 secondi affinché la consegna venga considerata avvenuta con successo; i reindirizzamenti non vengono seguiti. - Le consegne non riuscite (timeout, errore di connessione o codice non
2xx) vengono ritentate automaticamente: 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore dopo il fallimento precedente, con un massimo di 6 tentativi per evento, dopodiché non verranno più ripetute. - I tentativi di ripetizione vengono inviati all’URL corrente del webhook con il corpo invariato (
timestamp,datae la firma corrispondono alla prima consegna; sesecretè cambiato nel frattempo, viene utilizzata la nuova firmasecret); gli eventi già consegnati non vengono inviati nuovamente. - Quando un webhook viene disabilitato, eliminato o non è più iscritto all’evento, i relativi tentativi di retry in sospeso vengono annullati.
- I receiver dovrebbero gestire gli eventi in modo idempotente secondo
data.job_idedata.statuse rispondere rapidamente dopo averli salvati in modo sicuro. - I webhook multipli di un singolo account vengono inviati in parallelo; un destinatario lento non rallenta gli altri.
- Dopo 10 consegne consecutive fallite (inclusi i tentativi di ripetizione), il webhook viene disabilitato automaticamente; riattivalo con
PATCHuna volta risolto il problema del destinatario. GET /api/v1/webhooksmostra l’ora dell’ultimo trigger, il codice di stato e i tentativi consecutivi di ogni webhook