Webhooks
Une fois l’URL de webhook configurée, votre serveur est notifié lorsque le traitement d’une traduction de fichier (/jobs) se termine (avec succès ou non). Les tâches annulées via POST /jobs/{id}/cancel ne génèrent aucun rappel. Pour les opérations sur documents et les tâches multimédias, interrogez leurs propres points de requête.
Gérer les webhooks
Section intitulée « Gérer les webhooks »Géré via l’API, jusqu’à 3 par utilisateur :
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteCréer un exemple :
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" }'L’URL doit être accessible depuis Internet public, de préférence via HTTPS ; les réseaux privés, les adresses locales et les URL malformées renvoient 400. La requête PATCH peut modifier url, secret, events, description et status (active / disabled).
Format du rappel
Section intitulée « Format du rappel »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 }}Événements
Section intitulée « Événements »| Événement | Lorsque |
|---|---|
job.completed | Un travail se termine ; data.status est completed ou failed |
Les tâches ayant échoué utilisent également l’événement job.completed ; distinguez-les grâce à data.status == "failed" et à l’optionnel data.error. Les tâches réussies ne comportent aucun champ error. data.char_count correspond au nombre de caractères dans la traduction, 0 pour les tâches ayant échoué.
events n’accepte que job.completed et * (tous les événements) ; d’autres valeurs ou une liste vide renvoient le code 422. Dans une requête PATCH, omettez les champs que vous ne modifiez pas ; l’envoi de null renvoie également le code 422.
Vérifiez la signature
Section intitulée « Vérifiez la signature »Lorsque vous définissez un secret sur le webhook, chaque rappel transporte X-Webhook-Signature. Vérifiez-le avec HMAC-SHA256 via le corps de requête brut :
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 eventLa signature ne couvre que le corps, pas les en-têtes. Pour la protection contre les rejeux, vérifiez timestamp dans le corps une fois la signature validée (il est égal à X-Webhook-Timestamp, mais seul la valeur du corps est signée), et effectuez la déduplication via data.job_id et data.status. Les tentatives de relais renvoient le corps de la première livraison sans modification, avec la même valeur de timestamp, et la dernière tentative intervient environ 8,6 heures après la première livraison ; ne réduisez donc pas cette fenêtre au-delà de ce délai (l’exemple utilise 12 heures).
Livraison
Section intitulée « Livraison »- Le destinataire doit renvoyer
2xxdans un délai de 15 secondes pour que la livraison soit considérée comme réussie ; les redirections ne sont pas suivies. - Les livraisons échouées (timeout, erreur de connexion ou non-
2xx) sont automatiquement reprises : 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures après l’échec précédent, avec un maximum de 6 tentatives par événement, puis plus aucune. - Les tentatives de réessai sont envoyées à l’URL actuelle du webhook, avec le corps inchangé (
timestamp,dataet la signature correspondent à la première livraison ; si lesecreta changé entre-temps, c’est le nouveausecretqui est utilisé) ; les événements déjà livrés ne sont pas renvoyés. - Lorsqu’un webhook est désactivé, supprimé ou qu’il n’est plus abonné à l’événement, ses tentatives de réacheminement en attente sont annulées.
- Les récepteurs doivent traiter les événements de manière idempotente conformément aux spécifications
data.job_idetdata.status, et répondre rapidement après les avoir persistés en toute sécurité. - Les multiples webhooks d’un même compte sont livrés en parallèle ; un récepteur lent n’entrave pas les autres.
- Après 10 livraisons consécutives échouées (y compris les tentatives de relance), le webhook est automatiquement désactivé ; réactivez-le avec
PATCHune fois le destinataire réparé. GET /api/v1/webhooksaffiche l’heure du dernier déclenchement, le code d’état et le nombre d’échecs consécutifs de chaque webhook