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

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

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

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

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

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

{
  "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",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Έγκυροι τύποι συμβάντων#

Το events επικυρώνεται ως προς αυτό το ακριβές σύνολο — τιμές εκτός της λίστας επιστρέφουν 400. Δείτε τον Κατάλογο συμβάντων για τη δομή του φορτίου κάθε τύπου.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded, call.data_extracted
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

Το issue.escalated δεν έχει περιβάλλον πράκτορα και παραδίδεται μόνο σε τελικά σημεία σε επίπεδο οργανισμού.

Τα voice.ready και voice.failed δεν μπορούν να επιλεγούν ρητά. Για να τα λαμβάνετε, δημιουργήστε ένα τελικό σημείο σε επίπεδο οργανισμού με events: []. Μια κενή λίστα συμβάντων λαμβάνει κάθε υποστηριζόμενο συμβάν εκτός από τα telephony.turn και web.turn, τα οποία πρέπει να επιλεγούν ρητά.

Καταστάσεις τελικών σημείων#

• active — οι παραδόσεις πραγματοποιούνται κανονικά.
• disabled — τίθεται μη αυτόματα σε παύση μέσω PATCH. Δεν αποστέλλονται αιτήματα. Δεν αλλάζουμε ποτέ την κατάσταση ενός τελικού σημείου disabled· η επαναφορά του σε active είναι πάντα δική σας επιλογή.
• failing — ορίζεται αυτόματα όταν μια παράδοση στο τελικό σημείο εξαντλήσει ολόκληρο το πρόγραμμα επαναλήψεων της (8 προσπάθειες σε 24 ώρες) χωρίς να λάβει ποτέ 2xx. Ένα τελικό σημείο που αποτυγχάνει δεν λαμβάνει περαιτέρω κίνηση. Αφού διορθωθεί το τελικό σημείο, επαναφέρετε την κατάστασή του σε 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, δεν το φτάνουν ποτέ. Μπορείτε επίσης να δημιουργείτε και να διαχειρίζεστε αυτά τα τελικά σημεία από την ενότητα Διαδικτυακά άγκιστρα του δημιουργού πρακτόρων.

Δημιουργία τελικού σημείου#

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"]

Πεδία αιτήματος#

Επιστρέφει 201 Created με το ενημερωμένο αντικείμενο τελικού σημείου και ένα πρόσθετο πεδίο 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"
}

Ενημέρωση τελικού σημείου#

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

Επιστρέφει 200 OK με το ενημερωμένο αντικείμενο τελικού σημείου.

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

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

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Το τελικό σημείο λαμβάνει έναν φάκελο όπως ο παρακάτω:

{
  "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 ενός τελικού σημείου. Εάν η πρώτη προσπάθεια αποτύχει, η παράδοση ακολουθεί το ίδιο χρονοδιάγραμμα επαναλήψεων με τις κανονικές παραδόσεις συμβάντων.

Για να διαμορφώσετε έναν ενεργοποιητή για πραγματικό σχήμα συμβάντος, περάστε ένα προαιρετικό 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.

Διαγραφή τελικού σημείου#

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 → Πρόσφατες παραδόσεις. Οι γραμμές εμφανίζουν την ετικέτα του τελικού σημείου και την προέλευση URL που χρησιμοποιήθηκε από την πιο πρόσφατη προσπάθεια. Αυτή είναι λειτουργική κατάσταση και όχι αμετάβλητο αρχείο ελέγχου: η διαγραφή ενός τελικού σημείου διαγράφει επίσης τις γραμμές παραδόσεών του.

Για ένα 404 του n8n, επιβεβαιώστε πρώτα ότι η ροή εργασίας είναι ενεργή, δέχεται POST και χρησιμοποιεί τη διεύθυνση URL webhook παραγωγής αντί για τη διεύθυνση URL δοκιμής. Ένα 401 ή 403 υποδεικνύει έλεγχο ταυτότητας ή επικύρωση υπογραφής· τα χρονικά όρια υποδεικνύουν καθυστέρηση ή διαθεσιμότητα προορισμού· τα σφάλματα TLS υποδεικνύουν την αλυσίδα πιστοποιητικών, το όνομα κεντρικού υπολογιστή ή τη λήξη.

Σχετικά#