Ga naar inhoud

Webhooks

Wanneer een webhook-URL is geconfigureerd, wordt uw server op de hoogte gesteld wanneer een bestandstranslatietaak (/jobs) eindigt (met of zonder succes). Tassen die met POST /jobs/{id}/cancel zijn geannuleerd, sturen geen callback. Voor documentbewerkingen en mediataken moet u hun eigen query-eindpunten raadplegen.

Beheerd via de API, maximaal 3 per gebruiker:

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

Maak een voorbeeld:

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

De URL moet bereikbaar zijn vanaf het openbare internet, bij voorkeur via HTTPS; privénetwerken, lokale adressen en ongeldige URL’s retourneren 400. PATCH kan url, secret, events, description en status wijzigen (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
}
}
EvenementWanneer
job.completedEen taak eindigt; data.status is completed of failed

Mislukte taken gebruiken ook het job.completed-event; onderscheid ze aan de hand van data.status == "failed" en het optionele data.error. Geslaagde taken bevatten geen error-veld. data.char_count is het aantal tekens in de vertaling, 0 voor mislukte taken.

events accepteert alleen job.completed en * (alle gebeurtenissen); andere waarden of een lege lijst retourneren 422. Houd bij een PATCH de velden die u niet wijzigt weg; het verzenden van null retourneert ook 422.

Wanneer u een secret op de webhook instelt, bevat elke callback X-Webhook-Signature. Verifieer dit met HMAC-SHA256 via de ruwe verzoekbody :

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

De handtekening dekt alleen de body, niet de headers. Voor replaybescherming controleert u timestamp in de body nadat de handtekening is geslaagd (deze komt overeen met X-Webhook-Timestamp, maar alleen de body-waarde wordt ondertekend), en voert u deduplicatie uit volgens data.job_id en data.status. Bij retries wordt de body van de eerste bezorging ongewijzigd opnieuw verzonden, met dezelfde timestamp, en de laatste retry vindt ongeveer 8,6 uur na de eerste bezorging plaats; maak het venster dus niet korter dan dat (het voorbeeld gebruikt 12 uur).

  • De ontvanger moet 2xx binnen 15 seconden terugsturen om de levering als geslaagd te laten tellen; redirects worden niet gevolgd.
  • Mislukte bezorgingen (time-out, verbindingsfout of niet-2xx) worden automatisch opnieuw geprobeerd: 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur na de vorige mislukking, maximaal 6 bezorgingen per gebeurtenis, daarna geen verdere pogingen.
  • Opnieuw pogingen worden naar de huidige URL van de webhook gestuurd met een ongewijzigd lichaam (timestamp, data en de handtekening komen overeen met de eerste bezorging; als de secret tussentijds is gewijzigd, wordt de nieuwe secret gebruikt); reeds bezorgde gebeurtenissen worden niet opnieuw verzonden.
  • Wanneer een webhook is uitgeschakeld, verwijderd of niet langer op het evenement is geabonneerd, worden de hangende herprobeeracties geannuleerd.
  • Ontvangers dienen gebeurtenissen idempotent te verwerken volgens data.job_id en data.status, en snel te reageren nadat ze veilig zijn opgeslagen.
  • Meerdere webhooks van één account worden parallel afgeleverd; een trage ontvanger vertraagt de overige niet.
  • Na 10 opeenvolgende mislukte bezorgingen (inclusief herpogingen) wordt de webhook automatisch uitgeschakeld; schakel deze opnieuw in met PATCH zodra de ontvanger is gerepareerd.
  • GET /api/v1/webhooks toont de laatste activeringstijd, statuscode en opeenvolgende fouten van elke webhook