Webhooks
Po skonfigurowaniu adresu URL webhooka, Twój serwer otrzymuje powiadomienie po zakończeniu zadania tłumaczenia pliku (/jobs) – niezależnie od wyniku. Zadania anulowane za pomocą POST /jobs/{id}/cancel nie generują żadnego callbacku. W przypadku operacji na dokumentach i zadań dotyczących multimediów należy pobierać status za pomocą ich własnych punktów końcowych zapytań.
Zarządzaj webhookami
Dział zatytułowany „Zarządzaj webhookami”Obsługiwane za pomocą interfejsu API, maksymalnie 3 na użytkownika:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteUtwórz przykład:
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" }'Adres URL musi być dostępny z publicznego Internetu, najlepiej za pośrednictwem HTTPS; sieci prywatne, adresy lokalne i nieprawidłowe adresy URL powodują błąd 400. Operacja PATCH może zmieniać wartości url, secret, events, description oraz status (active / disabled).
Format funkcji callback
Dział zatytułowany „Format funkcji 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 }}Zdarzenia
Dział zatytułowany „Zdarzenia”| Zdarzenie | Kiedy |
|---|---|
job.completed | Zadanie się kończy; data.status jest completed lub failed |
Niepowodzące zadania również wykorzystują zdarzenie job.completed; odróżnia je po data.status == "failed" oraz opcjonalnym data.error. Powodujące zadania nie zawierają pola error. data.char_count to liczba znaków w tłumaczeniu, a dla niepowodujących zadań 0.
events akceptuje wyłącznie job.completed i * (wszystkie zdarzenia); inne wartości lub pusta lista powodują zwrócenie kodu 422. W żądaniu PATCH należy pomijać pola, które nie są zmieniane; wysłanie null również powoduje zwrócenie kodu 422.
Zweryfikuj podpis
Dział zatytułowany „Zweryfikuj podpis”Gdy ustawiasz secret na webhooku, każde wywołanie zwrotne zawiera X-Webhook-Signature. Zweryfikuj to za pomocą HMAC-SHA256 w ramach /nieskompresowanej treści żądania :
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 eventPodpis obejmuje wyłącznie ciało wiadomości, nie nagłówki. W celu ochrony przed odtworzeniem po zatwierdzeniu podpisu należy sprawdzić timestamp w ciele wiadomości (ma tę samą wartość co X-Webhook-Timestamp, jednak podpisuje się tylko wartość ciała), a następnie usunąć duplikaty za pomocą data.job_id i data.status. Próby ponownego wysłania przesyłają niezmienione ciało pierwszej dostawy, z tym samym timestamp, a ostatnia próba następuje około 8,6 godziny po pierwszej dostawie, dlatego okno nie powinno być krótsze niż ten czas (w przykładzie użyto 12 godzin).
Dostawa
Dział zatytułowany „Dostawa”- Odbiorca musi zwrócić
2xxw ciągu 15 sekund, aby dostawa została uznana za udaną; przekierowania nie są obsługiwane. - Nieudane dostawy (timeout, błąd połączenia lub inny niż
2xx) są automatycznie powtarzane: 1 minutę, 5 minut, 30 minut, 2 godziny i 6 godzin po poprzednim niepowodzeniu, maksymalnie 6 prób na każde zdarzenie, następnie bez dalszych próbow. - Próby ponownego wysłania są kierowane do aktualnego URL webhooka z niezmienionym treścią (
timestamp,datai podpisem, który odpowiada pierwszej dostawie; jeśli w międzyczasie zmienił sięsecret, nowysecretjest używany do podpisu); zdarzenia, które zostały już dostarczone, nie są wysyłane ponownie. - Gdy webhook jest wyłączony, usunięty lub nie jest już subskrybowany do danego zdarzenia, jego oczekujące próby ponownego wysłania są anulowane.
- Odbiorniki powinny obsłużyć zdarzenia deklaratywnie zgodnie z
data.job_ididata.statusoraz szybko reagować po ich bezpiecznym persistencji. - Wiele webhooków z jednego konta jest dostarczanych równolegle; powolny odbiorca nie opóźnia przesyłania pozostałych.
- Po 10 kolejnych nieudanych dostawach (w tym próbach ponownych) webhook jest automatycznie wyłączany; włącz go ponownie za pomocą
PATCH, gdy odbiorca zostanie naprawiony. GET /api/v1/webhookspokazuje ostatni czas wyzwalania każdego webhooka, kod statusu oraz liczbę kolejnych błędów.