Zum Inhalt springen

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.

Über die API verwaltet, maximal 3 pro Benutzer:

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

Erstellen Sie ein Beispiel:

Terminal-Fenster
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.

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
}
}
EreignisWenn
job.completedEin 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.

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

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

  • Der Empfänger muss 2xx innerhalb 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, data und die Signatur entsprechen der ersten Zustellung; falls sich zwischenzeitlich der secret geändert hat, wird der neue secret verwendet); 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_id und data.status idempotent 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 PATCH erneut.
  • GET /api/v1/webhooks zeigt die letzte Auslösezeit, den Statuscode und die aufeinanderfolgenden Fehler jedes Webhooks an.