Sari la conținut

Webhooks

Cu o URL de webhook configurată, serverul dvs. este notificat atunci când un job de traducere a fișierului (/jobs) se încheie (cu succes sau nu). Joburile anulate cu POST /jobs/{id}/cancel nu trimit nicio apel de întoarcere. Pentru operațiile asupra documentelor și joburile media, consultați punctele de terminare de query proprii.

Gestionate prin intermediul API, până la 3 per utilizator:

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

Creați exemplu:

Terminal window
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"
}'

Adresa URL trebuie accesibilă din internetul public, de preferat prin HTTPS; rețele private, adrese locale și adrese URL malformed returnează 400. Comanda PATCH poate schimba url, secret, events, description și 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
}
}
EvenimentCând
job.completedO sarcină se încheie; data.status este completed sau failed

Treburile eșuate folosesc, de asemenea, evenimentul job.completed; diferențiați-le prin data.status == "failed" și prin data.error, care este opțional. Treburile reușite nu conțin niciun câmp error. data.char_count reprezintă numărul de caractere din traducere, iar pentru treburile eșuate valoarea este 0.

events acceptă doar job.completed și * (toate evenimentele); alte valori sau o listă goală returnează 422. Într-o operațiune PATCH, lăsați în afara cererii câmpurile pe care nu le modificați; trimiteți de asemenea null pentru a obține un cod 422.

Când setați un secret pe webhook, fiecare callback transportă X-Webhook-Signature. Verificați-l cu HMAC-SHA256 pe corpusul cererii brute :

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

Semnătura acoperă doar corpul mesajului, nu și capetele. Pentru protecția împotriva redeschiderii, verificați timestamp în corp după validarea semnăturii (acesta este egal cu X-Webhook-Timestamp, dar doar valoarea corpului este semnată), iar deduplarea se face prin data.job_id și data.status. Retrimiterea reîncercărilor trimite corpul primei livrări fără modificări, cu același timestamp, iar ultima retrimitere are loc aproximativ 8,6 ore după prima livrare, deci nu reduceți intervalul mai mult decât atât (exemplul folosește 12 ore).

  • Receptorul trebuie să returneze 2xx în termen de 15 secunde pentru ca livrarea să fie considerată reușită; redirectionările nu sunt urmate.
  • Livrările eșuate (timeout, eroare de conexiune sau non-2xx) sunt reîncercate automat: la 1 minut, 5 minute, 30 de minute, 2 ore și 6 ore după eșecul anterior, cu un maximum de 6 livrări per eveniment, apoi nu mai sunt efectuate.
  • Retrimiteri sunt direcționate către URL-ul curent al webhook-ului, cu corpul neschimbat (timestamp, data și semnătura corespund primei livrări; dacă secret s-a schimbat între timp, noua valoare a secret este folosită pentru semnare); evenimentele deja livrate nu sunt trimise din nou.
  • Când un webhook este dezactivat, șters sau nu mai este abonat la eveniment, retrimiterile sale pendente sunt anulate.
  • Receptorii ar trebui să proceseze evenimentele în mod idempotent prin data.job_id și data.status, și să răspundă rapid după persistarea lor în siguranță.
  • Mai multe webhook-uri ale unui singur cont sunt livrate în paralel; un receptor lent nu încetinește procesarea celorlalte.
  • După 10 livrări consecutive eșuate (inclusiv retragerile), webhook-ul este dezactivat automat; reactivați-l folosind PATCH odată ce destinatarul este reparat.
  • GET /api/v1/webhooks afișează ora ultimei declanșări, codul de stare și eșecurile consecutive ale fiecărui webhook