Webhooks
Με μια διαμορφωμένη διεύθυνση URL webhook, ο διακομιστής σας ειδοποιείται όταν ολοκληρώνεται μια εργασία μετάφρασης αρχείου (/jobs) (επιτυχώς ή όχι). Οι εργασίες που ακυρώνονται με POST /jobs/{id}/cancel δεν αποστέλλουν καμία ανατροφοδότηση. Για λειτουργίες εγγράφων και εργασίες πολυμέσων, ελέγξτε τα δικά τους endpoint ερωτήσεων.
Διαχείριση webhooks
Section titled “Διαχείριση webhooks”Διαχειρίζονται μέσω της API, έως 3 ανά χρήστη:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteΔημιουργήστε παράδειγμα:
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" }'Η διεύθυνση URL πρέπει να είναι προσβάσιμη από το δημόσιο Διαδίκτυο, κατά προτίμηση μέσω HTTPS; ιδιωτικά δίκτυα, τοπικές διευθύνσεις και εσφαλμένες διευθύνσεις URL επιστρέφουν 400. Το PATCH μπορεί να αλλάξει τα url, secret, events, description και status (active / disabled).
Μορφή callback
Section titled “Μορφή 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 }}Εκδηλώσεις
Section titled “Εκδηλώσεις”| Γεγονός | Όταν |
|---|---|
job.completed | Μια εργασία τελειώνει· το data.status είναι completed ή failed |
Οι αποτυχημένες εργασίες χρησιμοποιούν επίσης το γεγονός job.completed; διακρίνετέ τες με βάση το data.status == "failed" και το προαιρετικό data.error. Οι επιτυχημένες εργασίες δεν περιέχουν πεδίο error. Το data.char_count είναι ο αριθμός των χαρακτήρων στη μετάφραση, ενώ για τις αποτυχημένες εργασίες είναι 0.
Το events αποδέχεται μόνο τα job.completed και * (όλα τα γεγονότα); άλλες τιμές ή μια κενή λίστα επιστρέφουν 422. Σε μια ΠΡΟΣΑΡΜΟΓΗ, παραλείψτε τα πεδία που δεν αλλάζετε· η αποστολή του null επίσης επιστρέφει 422.
Επαληθεύστε την υπογραφή
Section titled “Επαληθεύστε την υπογραφή”Όταν ορίζετε ένα secret στο webhook, κάθε callback περιέχει X-Webhook-Signature. Επιβεβαιώστε το με HMAC-SHA256 στο raw request body :
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 eventΗ υπογραφή καλύπτει μόνο το σώμα, όχι τα πεδία επικεφαλίδων. Για προστασία από αναπαραγωγή, ελέγξτε το timestamp στο σώμα αφού περάσει η υπογραφή (ισούται με το X-Webhook-Timestamp, αλλά υπογράφεται μόνο η τιμή του σώματος), και αφαιρέστε τις διπλές εγγραφές με τα data.job_id και data.status. Οι επαναπροσπάθησεις αποστέλλουν το σώμα της πρώτης παράδοσης αμετάβλητο, με την ίδια timestamp, και η τελευταία επαναπροσπάθεια γίνεται περίπου 8,6 ώρες μετά την πρώτη παράδοση, οπότε μην κάνετε το παράθυρο πιο σύντομο από αυτό (το παράδειγμα χρησιμοποιεί 12 ώρες).
Παράδοση
Section titled “Παράδοση”- Ο δέκτης πρέπει να επιστρέψει
2xxεντός 15 δευτερολέπτων για να θεωρηθεί επιτυχής η παράδοση· οι ανακατευθύνσεις δεν ακολουθούνται. - Οι αποτυχημένες παραδόσεις (παράταση χρόνου, σφάλμα σύνδεσης ή μη-
2xx) επαναλαμβάνονται αυτόματα: 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες και 6 ώρες μετά την προηγούμενη αποτυχία, το πολύ 6 παραδόσεις ανά γεγονός, στη συνέχεια όχι περισσότερες - Οι επαναληπτικές προσπάθειες αποστέλλονται στην τρέχουσα διεύθυνση URL του webhook με αμετάβλητο περιεχόμενο (
timestamp,dataκαι η υπογραφή ταιριάζει με την πρώτη παράδοση· εάν ηsecretέχει αλλάξει στο ενδιάμεσο, η νέαsecretχρησιμοποιείται για την υπογραφή); τα γεγονότα που έχουν ήδη παραδοθεί δεν αποστέλλονται ξανά. - Όταν ένας webhook απενεργοποιηθεί, διαγραφεί ή δεν είναι πλέον εγγεγραμμένος στο συγκεκριμένο γεγονός, οι εκκρεμείς επαναλήψεις του ακυρώνονται.
- Οι δέκτες θα πρέπει να χειρίζονται τα γεγονότα ιδεμποτέντως σύμφωνα με τα
data.job_idκαιdata.status, και να ανταποκρίνονται γρήγορα μετά την ασφαλή διατήρησή τους. - Πολλαπλά webhooks ενός λογαριασμού παραδίδονται παράλληλα· ένας αργός παραλήπτης δεν καθυστερεί τα υπόλοιπα
- Μετά από 10 συνεχόμενες αποτυχημένες παραδόσεις (συμπεριλαμβανομένων των επαναλήψεων), ο webhook απενεργοποιείται αυτόματα· ενεργοποιήστε τον ξανά με
PATCHμόλις διορθωθεί ο παραλήπτης. - Το
GET /api/v1/webhooksεμφανίζει την τελευταία ώρα ενεργοποίησης, τον κωδικό κατάστασης και τις συνεχόμενες αποτυχίες κάθε webhook