Webhooks
Nachdem eine Webhook-URL konfiguriert wurde, erhält Ihr Server eine Benachrichtigung, wenn ein Dateiübersetzungsjob (/jobs) beendet ist (erfolgreich oder nicht). Jobs, die mit POST /jobs/{id}/cancel abgebrochen wurden, senden keinen Rückruf. Für Dokumentoperationen und Medienjobs rufen Sie deren jeweiligen Abfrageendpunkte ab.
Webhooks verwalten
Abschnitt betitelt „Webhooks verwalten“Über die API verwaltet, maximal 3 pro Benutzer:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteErstellen Sie ein Beispiel:
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" }'Die URL muss über das öffentliche Internet erreichbar sein, vorzugsweise über HTTPS; private Netzwerke, lokale Adressen und fehlerhafte URLs führen zu 400. PATCH kann url, secret, events, description und status (active / disabled) ändern.
Callback-Format
Abschnitt betitelt „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 }}Ereignisse
Abschnitt betitelt „Ereignisse“| Ereignis | Wenn |
|---|---|
job.completed | Ein Job endet; data.status ist completed oder failed |
Fehlgeschlagene Aufträge verwenden ebenfalls das Ereignis job.completed; unterscheiden Sie sie anhand von data.status == "failed" und dem optionalen data.error. Erfolgreiche Aufträge enthalten kein Feld error. data.char_count gibt die Anzahl der Zeichen in der Übersetzung an, 0 bei fehlgeschlagenen Aufträgen.
events akzeptiert nur job.completed und * (alle Ereignisse); andere Werte oder eine leere Liste führen zu einem Fehlercode 422. Bei einem PATCH lassen Sie die Felder weg, die Sie nicht ändern; das Senden von null führt ebenfalls zu einem Fehlercode 422.
Signatur überprüfen
Abschnitt betitelt „Signatur überprüfen“Wenn Sie einen secret auf dem Webhook festlegen, enthält jeder Callback X-Webhook-Signature. Überprüfen Sie ihn mit HMAC-SHA256 über den rohen Anfragekörper:
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 eventDie Signatur umfasst nur den Nachrichtenkörper, nicht die Header. Zur Replay-Schutzprüfung prüfen Sie timestamp im Nachrichtenkörper, nachdem die Signatur bestanden wurde (es entspricht X-Webhook-Timestamp, jedoch wird nur der Körperwert signiert), und deduplizieren Sie mithilfe von data.job_id und data.status. Wiederholungsversuche senden den ursprünglichen Nachrichtenkörper unverändert mit demselben timestamp erneut; der letzte Wiederholungsversuch erfolgt etwa 8,6 Stunden nach der ersten Zustellung. Daher sollten Sie das Zeitfenster nicht kürzer als diesen Wert festlegen (im Beispiel werden 12 Stunden verwendet).
Lieferung
Abschnitt betitelt „Lieferung“- Der Empfänger muss
2xxinnerhalb von 15 Sekunden zurücksenden, damit die Zustellung als erfolgreich gilt; Weiterleitungen werden nicht folge German: - Fehlgeschlagene Zustellungen (Timeout, Verbindungsfehler oder Nicht-
2xx) werden automatisch erneut versucht: 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden nach dem vorherigen Fehlschlag; maximal 6 Versuche pro Ereignis, danach keine weiteren. - Neuversuche werden an die aktuelle URL des Webhooks gesendet, wobei der Body unverändert bleibt (
timestamp,dataund die Signatur entsprechen der ersten Zustellung; falls sich zwischenzeitlich dersecretgeändert hat, wird der neuesecretverwendet); bereits zugestellte Ereignisse werden nicht erneut gesendet. - Wenn ein Webhook deaktiviert, gelöscht oder nicht mehr für das Ereignis abonniert ist, werden seine ausstehenden Wiederholungsversuche storniert.
- Empfänger sollten Ereignisse gemäß
data.job_idunddata.statusidempotent verarbeiten und nach deren sicherer Persistierung schnell reagieren. - Mehrere Webhooks eines Kontos werden parallel zugestellt; ein langsamer Empfänger bremst die anderen nicht.
- Nach 10 aufeinanderfolgenden fehlgeschlagenen Zustellungen (einschließlich Wiederholungsversuchen) wird der Webhook automatisch deaktiviert; aktivieren Sie ihn nach Behebung des Empfängers mit
PATCHerneut. GET /api/v1/webhookszeigt die letzte Auslösezeit, den Statuscode und die aufeinanderfolgenden Fehler jedes Webhooks an.