Σημεία τερματισμού webhook

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

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

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

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

{
  "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"
}

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

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

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

Καταστάσεις τελικού σημείου

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

Εμφάνιση λίστας τελικών σημείων

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

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

Δημιουργία 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"]

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

Επιστρέφει 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"]
  }'

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

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

Στείλτε ένα συνθετικό συμβάν webhook.test σε ένα endpoint χρησιμοποιώντας την κανονική ροή παράδοσης, συμπεριλαμβανομένης της κανονικής σειριοποίησης JSON, του X-ThunderPhone-Signature, της καταγραφής παράδοσης και της παρακολούθησης επαναλήψεων. Η δοκιμή στοχεύει το επιλεγμένο 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. Αν η πρώτη προσπάθεια αποτύχει, η παράδοση ακολουθεί το ίδιο πρόγραμμα επαναλήψεων με τις κανονικές παραδόσεις συμβάντων.

Διαγράψτε ένα 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 διακόπτεται αμέσως· οι επαναλήψεις που βρίσκονται σε εξέλιξη εγκαταλείπονται.

Σχετικά