Επισκόπηση Webhooks

Πώς το ThunderPhone παραδίδει συμβάντα σε πραγματικό χρόνο, πώς να επαληθεύετε υπογραφές και πώς συγκρίνονται τα παλαιού τύπου και τα βασισμένα σε endpoint μοντέλα παράδοσης.

Το ThunderPhone στέλνει αιτήματα HTTP POST στον διακομιστή σας όταν συμβαίνουν ενέργειες κατά τη διάρκεια μιας κλήσης — ξεκινά μια εισερχόμενη κλήση, ολοκληρώνεται μια κλήση, ολοκληρώνεται μια εκτέλεση αξιολόγησης, ενεργοποιείται μια ειδοποίηση και ούτω καθεξής. Υπάρχουν δύο μοντέλα παράδοσης:

Όλοι οι τύποι συμβάντων που αναφέρονται στον κατάλογο συμβάντων παραδίδονται μέσω τελικών σημείων webhook. Τα έξι συμβάντα κύκλου ζωής κλήσης (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) αποστέλλονται επίσης στο webhook παλαιού τύπου με ένα URL — αν έχετε και URL παλαιού τύπου και αντίστοιχο τελικό σημείο, λαμβάνετε το συμβάν και από τις δύο διαδρομές. Η δεσμευτική συμπεριφορά (η ανταλλαγή διαμόρφωσης telephony.incoming / web.incoming και η δρομολόγηση εργαλείων σε λειτουργία webhook) υπάρχει αποκλειστικά στη διαδρομή παλαιού τύπου· κάθε παράδοση σε τελικό σημείο είναι ειδοποίηση αποστολής χωρίς αναμονή.

Μορφή payload#

Οι παραδόσεις σε τελικά σημεία είναι ένα αντικείμενο JSON με data, event_id και type:

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

Το event_id είναι μοναδικό για κάθε εκπεμπόμενο συμβάν. Είναι ίδιο σε όλες τις επαναλήψεις και σε κάθε τελικό σημείο που λαμβάνει το συμβάν — κάντε αποδιπλοποίηση βάσει αυτού.

Το webhook παλαιού τύπου με ένα URL στέλνει τα ίδια type και data, αλλά χωρίς event_id:

{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}

Κατά τη μετάδοση, κάθε σώμα σειριοποιείται κανονικά — τα κλειδιά ταξινομούνται αλφαβητικά, χωρίς κενά, σε UTF-8. Τα παραδείγματα με μορφοποίηση σε πολλές γραμμές σε αυτή την τεκμηρίωση προορίζονται μόνο για αναγνωσιμότητα.

Δείτε τον Κατάλογο συμβάντων για την πλήρη λίστα τύπων συμβάντων και πεδίων payload.

Επαλήθευση υπογραφής#

Κάθε αίτημα φέρει δύο υπογραφές, και οι δύο HMAC-SHA256 με κλειδί το secret του endpoint (ή το secret του webhook σε επίπεδο οργανισμού για παλαιές παραδόσεις):

• Το X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> υπογράφει τη χρονική σήμανση, τη μέθοδο, τη διαδρομή και το ερώτημα, καθώς και το ακατέργαστο σώμα. Επαληθεύστε αυτήν και απορρίψτε αιτήματα των οποίων το t απέχει περισσότερο από 5 λεπτά από το ρολόι σας, ώστε ένα υποκλαπέν αίτημα να μην μπορεί να επαναληφθεί αργότερα. Οι επαναλήψεις υπογράφονται ξανά όταν αποστέλλονται.
• Το X-ThunderPhone-Signature υπογράφει μόνο το ακατέργαστο σώμα. Εξακολουθεί να αποστέλλεται, χωρίς αλλαγές, ώστε οι υπάρχοντες επαληθευτές να συνεχίσουν να λειτουργούν.

Βήματα#

1. Διαβάστε την κεφαλίδα, τη μέθοδο, την ακατέργαστη διαδρομή και το ερώτημα, και το ακατέργαστο σώμα πριν από οποιαδήποτε ανάλυση.
2. Υπολογίστε το δεκαεξαδικό HMAC-SHA256 του <t>\n<METHOD>\n<path and query>\n<body> με το μυστικό σας.
3. Απορρίψτε το αίτημα αν το t απέχει περισσότερο από 300 δευτερόλεπτα ή αν το αποτέλεσμα δεν αντιστοιχεί στο v1 σε σύγκριση σταθερού χρόνου.

Τα σώματα είναι η κανονική σειριοποίηση JSON (ταξινομημένα κλειδιά, συμπαγείς διαχωριστές) και υπογράφουμε ακριβώς τις οκτάδες που μεταδίδουμε. Ο οδηγός επαλήθευσης περιλαμβάνει την ακριβή υπογεγραμμένη συμβολοσειρά, ένα αναλυτικό παράδειγμα, κώδικα χωρίς το SDK και την παλαιότερη κεφαλίδα.

from flask import Flask, abort, request
from thunderphone import verify_signature
 
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);

Σημασιολογία παράδοσης#

Αυτές οι σημασιολογικές αρχές ισχύουν για παραδόσεις σε τελικά σημεία. Η παλαιού τύπου διαδικτυακή ειδοποίηση μίας διεύθυνσης URL είναι μία σύγχρονη προσπάθεια χωρίς επαναλήψεις, εκτός από την ανταλλαγή ρυθμίσεων για τηλεφωνικές κλήσεις telephony.incoming, η οποία επαναλαμβάνεται μία φορά.

Επιλογή μεταξύ webhook παλαιού τύπου και webhook βάσει τελικών σημείων#

Οι νέες ενσωματώσεις θα πρέπει να καταναλώνουν συμβάντα μέσω webhook βάσει τελικών σημείων. Διατηρήστε (ή προσθέστε) μια διεύθυνση URL παλαιού τύπου μόνο αν ρυθμίζετε κλήσεις δυναμικά τη στιγμή της απάντησης ή χρησιμοποιείτε εκτέλεση εργαλείων σε λειτουργία webhook — αυτές οι ανταλλαγές αιτήματος/απόκρισης εκτελούνται μόνο στη διαδρομή παλαιού τύπου.

Σχετικά#