Open in
Τελικά σημεία webhook
Διαχειριστείτε πολλαπλά URL webhook με μυστικά ανά τελικό σημείο και φίλτρα συμβάντων.
Το σύστημα webhook βάσει endpoints σάς επιτρέπει να καταχωρίζετε πολλαπλούς προορισμούς ανά οργανισμό, καθέναν με το δικό του μυστικό, τη δική του κατάσταση και τη δική του συνδρομή σε ένα υποσύνολο τύπων συμβάντων. Αυτό είναι το προτεινόμενο μοντέλο για όλες τις νέες ενσωματώσεις.
Συγκρίνετέ το με το παλαιό webhook ενός URL, το οποίο διατηρείται για συμβατότητα προς τα πίσω, αλλά υποστηρίζει μόνο ένα URL ανά οργανισμό.
Endpoints
| Μέθοδος | Διαδρομή | Απαιτούμενος ρόλος | Περιγραφή |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | Λίστα τελικών σημείων |
POST | /v1/developer/webhook-endpoints | admin+ | Δημιουργία τελικού σημείου |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Ενημέρωση ετικέτας / URL / συμβάντων / κατάστασης |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Διαγραφή τελικού σημείου |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | Αντικατάσταση του μυστικού υπογραφής |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Αποστολή υπογεγραμμένης δοκιμαστικής παράδοσης |
GET | /v1/developer/webhook-deliveries | admin+ | Επιθεώρηση πρόσφατων αποτελεσμάτων τελικών σημείων και παλαιών παραδόσεων |
Αντικείμενο τελικού σημείου
{
"id": "c4d5e6f7-...",
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
"status": "active",
"agent_id": 42,
"agent_name": "Support Agent",
"secret_hint": "a1b2…9f0e",
"paused_at": null,
"pause_last_error": "",
"pause_undelivered_count": null,
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z"
}| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
id | UUID | Αναγνωριστικό endpoint |
label | συμβολοσειρά | Εμφανιζόμενο όνομα, 1–120 χαρακτήρες |
url | συμβολοσειρά | URL HTTPS· το http://localhost επιτρέπεται για ανάπτυξη |
events | πίνακας συμβολοσειρών | Τύποι συμβάντων στους οποίους έχει γίνει εγγραφή (δείτε τις έγκυρες τιμές). Ο κενός πίνακας εγγράφεται σε όλα τα συμβάντα εκτός από τα συμβάντα μόνο με ρητή εγγραφή (telephony.turn / web.turn / call.status_changed) |
status | συμβολοσειρά | active, disabled (σε μη αυτόματη παύση) ή failing (ορίζεται αυτόματα όταν μια παράδοση εξαντλήσει το πρόγραμμα επαναλήψεων 24 ωρών χωρίς ούτε μία απόκριση 2xx) |
agent_id | ακέραιος | null | Ο πράκτορας στον οποίο περιορίζεται αυτό το endpoint· το null σημαίνει ότι ισχύει σε επίπεδο οργανισμού |
agent_name | συμβολοσειρά | null | Όνομα του πράκτορα στον οποίο περιορίζεται ή null για endpoint σε επίπεδο οργανισμού |
secret_hint | συμβολοσειρά | Οι πρώτοι 4 και οι τελευταίοι 4 χαρακτήρες του μυστικού υπογραφής με αποσιωπητικά (a1b2…9f0e) — επαρκούν για να αντιστοιχίσετε το μυστικό που αποθηκεύσατε τοπικά χωρίς να εκθέσετε την πλήρη τιμή |
paused_at | χρονική σήμανση | null | Πότε το ThunderPhone έθεσε το endpoint σε κατάσταση failing. null όταν είναι active ή disabled |
pause_last_error | συμβολοσειρά | Το τελευταίο σφάλμα παράδοσης όταν το endpoint τέθηκε σε παύση, για παράδειγμα HTTP 503: Service Unavailable. Κενό εκτός αν είναι failing |
pause_undelivered_count | ακέραιος | null | Συμβάντα που δεν παραδόθηκαν μετά την τελευταία επιτυχή παράδοση του endpoint, καταμετρημένα όταν τέθηκε σε παύση |
created_at, updated_at | χρονική σήμανση |
Έγκυροι τύποι συμβάντων
Το events επικυρώνεται με βάση ακριβώς αυτό το σύνολο — τιμές εκτός της λίστας
επιστρέφουν 400. Δείτε τον κατάλογο συμβάντων για τη
μορφή του φορτίου κάθε τύπου.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(δεσμευμένο· δεν εκπέμπεται ακόμη)scheduled.skipped,scheduled.failedcall.graded,call.data_extracted,call.transfer_completed,call.status_changedcampaign.completedissue.reported,issue.escalatedtest-call.completedalert.triggeredphone_number.spam_risk_changed
Τα issue.escalated και phone_number.spam_risk_changed δεν έχουν περιβάλλον πράκτορα και
παραδίδονται μόνο σε endpoint για ολόκληρο τον οργανισμό.
Τα voice.ready και voice.failed δεν μπορούν να επιλεγούν ρητά. Για να τα λαμβάνετε,
δημιουργήστε ένα endpoint για ολόκληρο τον οργανισμό με events: []. Μια κενή λίστα
συμβάντων λαμβάνει κάθε υποστηριζόμενο συμβάν, εκτός από τα telephony.turn, web.turn και
call.status_changed, τα οποία πρέπει να επιλεγούν ρητά.
Καταστάσεις τελικού σημείου
active— οι παραδόσεις πραγματοποιούνται κανονικά.disabled— τίθεται σε μη αυτόματη παύση μέσωPATCH. Δεν αποστέλλονται αιτήματα. Δεν αλλάζουμε ποτέ την κατάσταση ενός endpointdisabled· η επαναφορά του σεactiveείναι πάντα δική σας επιλογή.failing— ορίζεται αυτόματα όταν μια παράδοση στο endpoint εξαντλήσει ολόκληρο το πρόγραμμα επαναλήψεων της (8 προσπάθειες σε 24 ώρες) χωρίς να λάβει ποτέ απάντηση 2xx. Ένα endpoint σε κατάσταση αποτυχίας δεν λαμβάνει περαιτέρω κίνηση. Στέλνουμε email στους κατόχους και τους διαχειριστές του οργανισμού σας όταν συμβαίνει αυτό, και ο πίνακας ελέγχου εμφανίζει το endpoint σε παύση με κουμπί Επανενεργοποίηση. Μόλις διορθωθεί το endpoint, επαναφέρετε την κατάστασή του σεactiveμέσωPATCH· οι παραδόσεις των οποίων το πρόγραμμα επαναλήψεων δεν έχει ακόμη εξαντληθεί συνεχίζονται από το σημείο όπου σταμάτησαν.
Λίστα τελικών σημείων
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Επιστρέφει έναν πίνακα από αντικείμενα τελικού σημείου.
Περάστε ?agent_id=42 για να επιστρέψετε μόνο τα τελικά σημεία που περιορίζονται σε εκείνον τον πράκτορα.
Τελικά σημεία περιορισμένα σε πράκτορα
Τα τελικά σημεία σε επίπεδο οργανισμού λαμβάνουν κάθε συμβάν που αντιστοιχεί. Ένα τελικό σημείο με
agent_id λαμβάνει μόνο συμβάντα που αντιστοιχούν σε κλήσεις τις οποίες χειρίζεται εκείνος ο πράκτορας·
συμβάντα χωρίς περιβάλλον πράκτορα, όπως το alert.triggered, δεν φτάνουν ποτέ σε αυτό. Μπορείτε
επίσης να δημιουργήσετε και να διαχειριστείτε αυτά τα τελικά σημεία από την ενότητα
Webhook του εργαλείου δημιουργίας πρακτόρων.
Δημιουργία endpoint
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"]
}'result = requests.post(
"https://api.thunderphone.com/v1/developer/webhook-endpoints",
headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
json={
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
},
).json()
secret = result["secret"]
endpoint_id = result["id"]Πεδία αιτήματος
| Πεδίο | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
label | συμβολοσειρά | ναι | 1–120 χαρακτήρες |
url | συμβολοσειρά | ναι | URL HTTPS (το http επιτρέπεται μόνο για localhost / 127.0.0.1) |
events | πίνακας | όχι | Κενό/παραλειπόμενο εγγράφεται σε όλα τα συμβάντα εκτός από τα telephony.turn / web.turn / call.status_changed, που απαιτούν ρητή εγγραφή. Πρέπει να χρησιμοποιήσετε τις τιμές που παρατίθενται στους Έγκυρους τύπους συμβάντων· τα διπλότυπα καταργούνται |
agent_id | ακέραιος | null | όχι | Περιορίστε την παράδοση σε έναν πράκτορα σε αυτόν τον οργανισμό· παραλείψτε το ή χρησιμοποιήστε null για endpoint σε επίπεδο οργανισμού |
Επιστρέφει 201 Created με το αντικείμενο Endpoint, καθώς και
ένα επιπλέον πεδίο secret ανώτατου επιπέδου που περιέχει το ακατέργαστο κλειδί υπογραφής — μια
δεκαεξαδική συμβολοσειρά 48 χαρακτήρων:
{
"id": "c4d5e6f7-…",
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
"status": "active",
"secret_hint": "a1b2…9f0e",
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z",
"secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}Ενημέρωση endpoint
curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Production — Call + Grade events",
"events": ["telephony.incoming", "telephony.complete", "call.graded"]
}'| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
label | συμβολοσειρά | |
url | συμβολοσειρά | |
events | πίνακας | |
status | συμβολοσειρά | active ή disabled. Ορίστε active για να ενεργοποιήσετε ξανά ένα endpoint που ο διακομιστής επισήμανε ως failing |
agent_id | ακέραιος | null | Ορίστε αναγνωριστικό πράκτορα για να περιορίσετε το endpoint ή null για να το κάνετε σε επίπεδο οργανισμού |
Επιστρέφει 200 OK με το ενημερωμένο αντικείμενο Endpoint.
Περιστροφή του μυστικού υπογραφής
Αντικαταστήστε το μυστικό υπογραφής ενός endpoint, για παράδειγμα όταν χάθηκε ή ενδέχεται να διέρρευσε. Μπορείτε επίσης να χρησιμοποιήσετε τον πίνακα ελέγχου: ανοίξτε το endpoint στην ενότητα Ενσωματώσεις → Webhooks (εκεί εμφανίζονται τόσο τα endpoint σε επίπεδο οργανισμού όσο και τα endpoint πρακτόρων) και επιλέξτε Περιστροφή.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'| Πεδίο | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
include_copies | boolean | όχι | Προεπιλογή: true. Παρέχει επίσης το νέο μυστικό στα άλλα endpoint του οργανισμού σας που έχουν το ίδιο URL και το ίδιο τρέχον μυστικό, όπως αντίγραφα αυτού του endpoint σε άλλους πράκτορες, ώστε ένας παραλήπτης να συνεχίζει να επαληθεύει με ένα μυστικό |
Επιστρέφει 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
endpoint | object | Το αντικείμενο Endpoint με το νέο secret_hint του |
secret | string | Το νέο μυστικό υπογραφής. Επιστρέφεται μόνο σε αυτή την απόκριση |
rotated_endpoint_ids | array of UUID | Κάθε endpoint που χρησιμοποιεί πλέον το νέο μυστικό |
Αποστολή δοκιμαστικής παράδοσης
Στείλτε ένα συνθετικό συμβάν webhook.test σε ένα endpoint χρησιμοποιώντας την κανονική
ροή παράδοσης, συμπεριλαμβανομένης της κανονικής σειριοποίησης JSON, και των δύο
κεφαλίδων υπογραφής, της καταγραφής παράδοσης και της παρακολούθησης επαναλήψεων.
Η δοκιμή στοχεύει το επιλεγμένο endpoint ανεξάρτητα από το φίλτρο events του.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Το endpoint λαμβάνει έναν φάκελο όπως:
{
"data": {
"message": "ThunderPhone webhook test",
"sent_at": "2026-07-17T20:12:34.567890+00:00"
},
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"type": "webhook.test"
}Το API επιστρέφει 200 OK μετά την πρώτη προσπάθεια, ακόμη και αν ο προορισμός
επιστρέψει σφάλμα. Ελέγξτε τα success, status, response_code και error
για το αποτέλεσμα της παράδοσης:
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}Το webhook.test είναι συνθετικό και δεν μπορεί να προστεθεί στη συνδρομή events
ενός endpoint. Αν η πρώτη προσπάθεια αποτύχει, το ThunderPhone την επαναλαμβάνει μία φορά περίπου
ένα λεπτό αργότερα και έπειτα σταματά· η παράδοση εμφανίζει τότε status: "failed"
στις Παραδόσεις εντοπισμού σφαλμάτων. Μια δοκιμαστική παράδοση δεν επισημαίνει ποτέ
το endpoint ως failing.
Για να διαμορφώσετε έναν ενεργοποιητή βάσει πραγματικού σχήματος συμβάντος, περάστε ένα προαιρετικό
event_type. Η παράδοση παραμένει συνθετική και περιέχει "sample": true·
τα δείγματα που σχετίζονται με κλήσεις χρησιμοποιούν call_id: 0 και agent_id: 0.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event_type":"call.graded"}'Το event_type δέχεται οποιαδήποτε τιμή από τους Έγκυρους τύπους συμβάντων.
Η παράλειψή του διατηρεί τη γενική συμπεριφορά του webhook.test.
Τα δείγματα ολοκλήρωσης κλήσης (telephony.complete, web.complete) και call.data_extracted
περιλαμβάνουν τα πεδία δεδομένων προς συλλογή του ίδιου του πράκτορα κάτω από το
extracted_data.fields, με τιμές-προσωρινά σύμβολα, όπως και οι πραγματικές κλήσεις του. Για έναν
πράκτορα που δεν συλλέγει δεδομένα, το δείγμα ολοκλήρωσης κλήσης στέλνει
extracted_data: null, όπως και οι πραγματικές κλήσεις του, και το δείγμα call.data_extracted
έχει κενά fields (οι πραγματικές κλήσεις δεν στέλνουν ποτέ αυτό το συμβάν για έναν τέτοιο πράκτορα).
Το summary του δείγματος είναι null όταν η σύνοψη κλήσης του πράκτορα είναι απενεργοποιημένη. Σε
ένα endpoint πράκτορα, το δείγμα ακολουθεί αυτόν τον πράκτορα· σε ένα endpoint για ολόκληρο τον οργανισμό,
περάστε προαιρετικά ένα agent_id για να διαμορφωθεί βάσει ενός πράκτορα ή παραλείψτε το για το γενικό δείγμα.
Διαγραφή endpoint
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Επιστρέφει 204 No Content. Η παράδοση στη διεύθυνση URL σταματά αμέσως·
οι επαναλήψεις που βρίσκονται σε εξέλιξη εγκαταλείπονται.
Παραδόσεις εντοπισμού σφαλμάτων
Πριν συμπεράνετε ότι ένα webhook δεν στάλθηκε, ελέγξτε το
GET /v1/developer/webhook-deliveries.
Εμφανίζει πρόσφατες προσπάθειες και από τα δύο συστήματα webhook, συμπεριλαμβανομένων του αναγνωριστικού κλήσης,
της προέλευσης URL, της κατάστασης HTTP, του αριθμού προσπαθειών, της κατηγορίας επιτρεπόμενης αποτυχίας και του επόμενου
χρόνου επανάληψης. Δεν επιστρέφει ποτέ το ωφέλιμο φορτίο συμβάντος, την απομαγνητοφώνηση, το αποθηκευμένο κείμενο σφάλματος,
το σώμα απόκρισης ή τη διαδρομή URL.
Μπορείτε επίσης να δείτε το ίδιο πρόσφατο ιστορικό στις Πράκτορες → επιλέξτε έναν πράκτορα → Webhooks → Πρόσφατες παραδόσεις. Οι γραμμές εμφανίζουν την ετικέτα endpoint και την προέλευση URL που χρησιμοποιήθηκε από την πιο πρόσφατη προσπάθεια. Πρόκειται για λειτουργική κατάσταση και όχι για αμετάβλητο αρχείο ελέγχου: η διαγραφή ενός endpoint διαγράφει επίσης τις γραμμές παράδοσής του.
Για ένα 404 του n8n, επιβεβαιώστε πρώτα ότι η ροή εργασίας είναι ενεργή, δέχεται POST και χρησιμοποιεί
τη διεύθυνση URL webhook παραγωγής αντί για τη διεύθυνση URL δοκιμής. Ένα 401 ή 403 υποδεικνύει
έλεγχο ταυτότητας ή επικύρωση υπογραφής· τα χρονικά όρια υποδεικνύουν καθυστέρηση
ή διαθεσιμότητα προορισμού· τα σφάλματα TLS υποδεικνύουν την αλυσίδα πιστοποιητικών, το όνομα κεντρικού υπολογιστή ή τη λήξη.