Το ThunderPhone v3 είναι πλέον διαθέσιμο.Ξεκινήστε μόνοι σας, από 2¢/λεπτό.Διαβάστε την ανακοίνωση

Webhooks

Τελικά σημεία webhook

Διαχειριστείτε πολλαπλά URL webhook με μυστικά ανά τελικό σημείο και φίλτρα συμβάντων.

Το σύστημα webhook βάσει endpoints σάς επιτρέπει να καταχωρίζετε πολλαπλούς προορισμούς ανά οργανισμό, καθέναν με το δικό του μυστικό, τη δική του κατάσταση και τη δική του συνδρομή σε ένα υποσύνολο τύπων συμβάντων. Αυτό είναι το προτεινόμενο μοντέλο για όλες τις νέες ενσωματώσεις.

Συγκρίνετέ το με το παλαιό webhook ενός URL, το οποίο διατηρείται για συμβατότητα προς τα πίσω, αλλά υποστηρίζει μόνο ένα URL ανά οργανισμό.

Endpoints

ΜέθοδοςΔιαδρομήΑπαιτούμενος ρόλοςΠεριγραφή
GET/v1/developer/webhook-endpointsadmin+Λίστα τελικών σημείων
POST/v1/developer/webhook-endpointsadmin+Δημιουργία τελικού σημείου
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-secretadmin+Αντικατάσταση του μυστικού υπογραφής
POST/v1/developer/webhook-endpoints/{endpoint_id}/testadmin+Αποστολή υπογεγραμμένης δοκιμαστικής παράδοσης
GET/v1/developer/webhook-deliveriesadmin+Επιθεώρηση πρόσφατων αποτελεσμάτων τελικών σημείων και παλαιών παραδόσεων

Αντικείμενο τελικού σημείου

{
  "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"
}
ΠεδίοΤύποςΠεριγραφή
idUUIDΑναγνωριστικό 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.turn
  • web.incoming, web.complete, web.tool, web.turn
  • sms.sent, sms.failed
  • sms.received (δεσμευμένο· δεν εκπέμπεται ακόμη)
  • scheduled.skipped, scheduled.failed
  • call.graded, call.data_extracted, call.transfer_completed, call.status_changed
  • campaign.completed
  • issue.reported, issue.escalated
  • test-call.completed
  • alert.triggered
  • phone_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. Δεν αποστέλλονται αιτήματα. Δεν αλλάζουμε ποτέ την κατάσταση ενός endpoint disabled· η επαναφορά του σε active είναι πάντα δική σας επιλογή.
  • failing — ορίζεται αυτόματα όταν μια παράδοση στο endpoint εξαντλήσει ολόκληρο το πρόγραμμα επαναλήψεων της (8 προσπάθειες σε 24 ώρες) χωρίς να λάβει ποτέ απάντηση 2xx. Ένα endpoint σε κατάσταση αποτυχίας δεν λαμβάνει περαιτέρω κίνηση. Στέλνουμε email στους κατόχους και τους διαχειριστές του οργανισμού σας όταν συμβαίνει αυτό, και ο πίνακας ελέγχου εμφανίζει το endpoint σε παύση με κουμπί Επανενεργοποίηση. Μόλις διορθωθεί το endpoint, επαναφέρετε την κατάστασή του σε active μέσω PATCH· οι παραδόσεις των οποίων το πρόγραμμα επαναλήψεων δεν έχει ακόμη εξαντληθεί συνεχίζονται από το σημείο όπου σταμάτησαν.

Λίστα τελικών σημείων

cURL
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
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"]
  }'
Python
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
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
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_copiesbooleanόχιΠροεπιλογή: true. Παρέχει επίσης το νέο μυστικό στα άλλα endpoint του οργανισμού σας που έχουν το ίδιο URL και το ίδιο τρέχον μυστικό, όπως αντίγραφα αυτού του endpoint σε άλλους πράκτορες, ώστε ένας παραλήπτης να συνεχίζει να επαληθεύει με ένα μυστικό

Επιστρέφει 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
ΠεδίοΤύποςΠεριγραφή
endpointobjectΤο αντικείμενο Endpoint με το νέο secret_hint του
secretstringΤο νέο μυστικό υπογραφής. Επιστρέφεται μόνο σε αυτή την απόκριση
rotated_endpoint_idsarray of UUIDΚάθε endpoint που χρησιμοποιεί πλέον το νέο μυστικό

Αποστολή δοκιμαστικής παράδοσης

Στείλτε ένα συνθετικό συμβάν webhook.test σε ένα endpoint χρησιμοποιώντας την κανονική ροή παράδοσης, συμπεριλαμβανομένης της κανονικής σειριοποίησης JSON, και των δύο κεφαλίδων υπογραφής, της καταγραφής παράδοσης και της παρακολούθησης επαναλήψεων. Η δοκιμή στοχεύει το επιλεγμένο endpoint ανεξάρτητα από το φίλτρο events του.

cURL
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
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 υποδεικνύουν την αλυσίδα πιστοποιητικών, το όνομα κεντρικού υπολογιστή ή τη λήξη.


Σχετικά