Przejdź do głównej zawartości

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

Obsługiwane za pomocą interfejsu API, maksymalnie 3 na użytkownika:

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

Utwórz przykład:

Okno terminala
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).

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
}
}
ZdarzenieKiedy
job.completedZadanie 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.

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

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

  • Odbiorca musi zwrócić 2xx w 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, data i podpisem, który odpowiada pierwszej dostawie; jeśli w międzyczasie zmienił się secret, nowy secret jest 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_id i data.status oraz 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/webhooks pokazuje ostatni czas wyzwalania każdego webhooka, kod statusu oraz liczbę kolejnych błędów.