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

Operations

Επαλήθευση υπογραφών webhook

Κάθε αίτημα webhook και εργαλείου που στέλνει το ThunderPhone υπογράφεται με χρονική σήμανση. Επαληθεύστε το με τη συνταγή ή το βοηθητικό SDK εδώ και απορρίψτε αιτήματα επανάληψης παλαιότερα των πέντε λεπτών.

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

ΚεφαλίδαΥπογράφειΠροστασία από επανάληψη
X-ThunderPhone-Signature-V2 (συνιστάται)Χρονική σήμανση, μέθοδο, διαδρομή, ερώτημα και σώμαΑπορρίψτε αιτήματα παλαιότερα από 5 λεπτά
X-ThunderPhone-SignatureΜόνο το σώμαΚαμία: ένα καταγεγραμμένο αίτημα επαληθεύεται για πάντα

Επαληθεύστε το X-ThunderPhone-Signature-V2 στις νέες ενσωματώσεις και μεταφέρετε τις υπάρχουσες σε αυτό. Το X-ThunderPhone-Signature εξακολουθεί να αποστέλλεται σε κάθε αίτημα, χωρίς αλλαγές, ώστε οι επαληθευτές που βασίζονται σε αυτό να συνεχίσουν να λειτουργούν. Θα ανακοινώσουμε ημερομηνία πριν σταματήσουμε να το στέλνουμε.

Υπογραφή V2

X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
  • Το t είναι η ώρα Unix, σε δευτερόλεπτα, κατά την οποία στείλαμε το αίτημα. Μια επαναλαμβανόμενη παράδοση υπογράφεται ξανά όταν αποστέλλεται, με το δικό της t.
  • Το v1 είναι το δεκαεξαδικό HMAC-SHA256 της υπογεγραμμένης συμβολοσειράς παρακάτω, με κλειδί το μυστικό σας.

Η τιμή είναι μια λίστα ζευγών key=value διαχωρισμένων με κόμμα. Αγνοήστε κλειδιά που δεν αναγνωρίζετε και αποδεχτείτε το αίτημα αν οποιοδήποτε v1 ταιριάζει: ενδέχεται να προσθέσουμε μια δεύτερη υπογραφή σε μελλοντική αλλαγή.

Η υπογεγραμμένη συμβολοσειρά

Τέσσερα πεδία, καθένα ακολουθούμενο από μία αλλαγή γραμμής (\n, byte 0x0A) εκτός από το τελευταίο:

<t>\n<METHOD>\n<path and query>\n<body>
ΠεδίοΤιμή
tΗ τιμή t από την κεφαλίδα
METHODΗ μέθοδος HTTP με κεφαλαία: POST, GET, PUT, PATCH ή DELETE
διαδρομή και ερώτημαΟ στόχος αιτήματος από τη γραμμή αιτήματος HTTP: η διαδρομή και, έπειτα, το ? και η συμβολοσειρά ερωτήματος όταν υπάρχει. Χωρίς σχήμα, κεντρικό υπολογιστή ή τμήμα. Χρησιμοποιήστε το ακριβώς όπως έφτασε, χωρίς αποκωδικοποίηση ή αναδιάταξη παραμέτρων
bodyΤο ακατέργαστο σώμα αιτήματος. Οι κλήσεις εργαλείων GET και DELETE δεν έχουν σώμα, επομένως η υπογεγραμμένη συμβολοσειρά τους τελειώνει με την αλλαγή γραμμής μετά τη διαδρομή

Για επαλήθευση:

  1. Πριν από οποιαδήποτε ανάλυση, διαβάστε την κεφαλίδα, τη μέθοδο, την ακατέργαστη διαδρομή και το ερώτημα, καθώς και το ακατέργαστο σώμα.
  2. Πάρτε το t και κάθε v1 από την κεφαλίδα.
  3. Απορρίψτε το αίτημα αν το t είναι περισσότερα από 300 δευτερόλεπτα πριν ή μετά από το ρολόι σας.
  4. Υπολογίστε το δεκαεξαδικό HMAC-SHA256 της υπογεγραμμένης συμβολοσειράς με το μυστικό σας.
  5. Συγκρίνετέ το με το v1 σε σταθερό χρόνο. Επιστρέψτε 401 αν δεν ταιριάζει τίποτα.

Παράδειγμα

Μυστικό whsec_example_4c1f2a9b. Στέλνουμε αυτό το αίτημα στις t = 1767225600 (2026-01-01 00:00:00 UTC):

POST /tools/lookup?region=us HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
 
{"customer_id":"cust_123"}

Η υπογεγραμμένη συμβολοσειρά είναι αυτές οι τέσσερις γραμμές, χωρίς αλλαγή γραμμής μετά το σώμα:

1767225600
POST
/tools/lookup?region=us
{"customer_id":"cust_123"}

Το HMAC-SHA256 της είναι 03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e. Ελέγξτε την υλοποίησή σας με αυτό ή αναπαραγάγετέ το με openssl:

printf '1767225600\nPOST\n/tools/lookup?region=us\n{"customer_id":"cust_123"}' \
  | openssl dgst -sha256 -hmac 'whsec_example_4c1f2a9b'

Μια κλήση εργαλείου GET προς /tools/lookup?customer_id=cust_123 στο ίδιο δευτερόλεπτο έχει κενό σώμα. Η υπογεγραμμένη συμβολοσειρά της είναι 1767225600\nGET\n/tools/lookup?customer_id=cust_123\n και η υπογραφή της είναι 3ce214cb0b8f2bf39b1d19d4e7265df9dbaff5a5f838d3cc6c753a8f7a4ad280.

Με τα SDK

Τα SDK για Python και TypeScript περιλαμβάνουν έναν βοηθό (thunderphone 0.2.0 ή νεότερο, @thunderphone/sdk 0.2.0 ή νεότερο). Ελέγχει το παράθυρο των 5 λεπτών, συγκρίνει σε σταθερό χρόνο και δέχεται μια λίστα μυστικών ώστε να μπορείτε να τα εναλλάσσετε χωρίς διακοπή λειτουργίας.

Python
from thunderphone import verify_signature
 
ok = verify_signature(
    header,            # the X-ThunderPhone-Signature-V2 value
    secret=SECRET,     # or [NEW_SECRET, OLD_SECRET] while rotating
    method=method,     # "POST"
    path=path,         # "/tools/lookup?region=us", exactly as received
    body=raw_body,     # bytes, before any JSON parsing
    tolerance=300,     # optional; seconds
)
Node.js
import { verifySignature } from "@thunderphone/sdk";
 
const ok = verifySignature({
  header,               // the X-ThunderPhone-Signature-V2 value
  secret: SECRET,       // or [NEW_SECRET, OLD_SECRET] while rotating
  method,               // "POST"
  path,                 // "/tools/lookup?region=us", exactly as received
  body: rawBody,        // Buffer or string, before any JSON parsing
  toleranceSeconds: 300, // optional
});

Χωρίς SDK

Python
import hashlib
import hmac
import time
 
TOLERANCE_SECONDS = 300
 
 
def verify_v2(header: str, secret: str, method: str, path: str, body: bytes) -> bool:
    """path is the path plus ?query exactly as received; body is the raw body."""
    timestamp, signatures = None, []
    for item in (header or "").split(","):
        key, _, value = item.strip().partition("=")
        if key == "t" and value.isdigit() and len(value) <= 15:
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}\n{method.upper()}\n{path}\n".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in signatures)
Node.js
import crypto from "node:crypto";
 
const TOLERANCE_SECONDS = 300;
 
// path is the path plus ?query exactly as received; body is the raw Buffer.
export function verifyV2(header, secret, method, path, body) {
  let timestamp;
  const signatures = [];
  for (const item of (header || "").split(",")) {
    const [key, value = ""] = item.trim().split("=", 2);
    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
    else if (key === "v1") signatures.push(value);
  }
  if (timestamp === undefined) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = Buffer.from(
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}\n${method.toUpperCase()}\n${path}\n`)
      .update(body)
      .digest("hex"),
  );
  return signatures.some((sig) => {
    const candidate = Buffer.from(sig);
    return (
      candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected)
    );
  });
}

Σύνδεση framework

Κάθε παράδειγμα διαβάζει την ακατέργαστη διαδρομή και το ερώτημα, καθώς και το ακατέργαστο σώμα, και στη συνέχεια καλεί τη βοηθητική συνάρτηση του SDK.

FastAPI
import json
 
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
 
app = FastAPI()
 
 
def raw_path_and_query(request: Request) -> str:
    path = (request.scope.get("raw_path") or request.url.path.encode()).decode("latin-1")
    query = request.scope.get("query_string", b"").decode("latin-1")
    return f"{path}?{query}" if query else path
 
 
@app.post("/thunderphone-webhook")
async def hook(request: Request):
    body = await request.body()  # raw bytes, NOT request.json()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=SECRET,
        method=request.method,
        path=raw_path_and_query(request),
        body=body,
    ):
        raise HTTPException(status_code=401)
    event = json.loads(body)
    # … dispatch on event["type"] …
    return {"ok": True}
Express
import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
 
app.post(
  "/thunderphone-webhook",
  // IMPORTANT: parse as raw; do NOT use express.json() here.
  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, // path and query as received
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // … dispatch on event.type …
    res.sendStatus(204);
  },
);
Django
import json
 
from django.http import HttpResponseForbidden, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from thunderphone import verify_signature
 
 
@csrf_exempt
@require_POST
def hook(request):
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=SECRET,
        method=request.method,
        path=request.get_full_path(),
        body=request.body,  # raw bytes
    ):
        return HttpResponseForbidden("invalid signature")
    event = json.loads(request.body)
    # … dispatch on event["type"] …
    return JsonResponse({"ok": True})

Το req.originalUrl (Express), καθώς και τα ASGI raw_path και query_string (FastAPI), αποτελούν τον στόχο ακριβώς όπως παραλήφθηκε. Το get_full_path() του Django και το request.path του Flask αποκωδικοποιούν πρώτα τη διαδρομή, κάτι που δίνει την ίδια συμβολοσειρά για συνήθεις διαδρομές. Αν η διαδρομή του endpoint σας περιέχει χαρακτήρες με ποσοστιαία κωδικοποίηση ή δεσμευμένους χαρακτήρες, όπως %2F, ; ή =, διαβάστε αντί γι’ αυτό τον ακατέργαστο στόχο που παρέχει ο διακομιστής σας (για παράδειγμα request.META["RAW_URI"] στο Gunicorn).

Ποιο μυστικό;

Το ίδιο μυστικό υπογράφει και τις δύο κεφαλίδες.

ΠηγήΜυστικό
Τελικό σημείο webhook (/v1/developer/webhook-endpoints)secret ανά τελικό σημείο (48 δεκαεξαδικοί χαρακτήρες), που επιστρέφεται μία φορά κατά τη δημιουργία
Παλαιού τύπου webhook με ένα URLsecret ανά οργανισμό που επιστρέφεται στο GET /v1/webhook
Επίκληση τελικού σημείου εργαλείου (άμεση κλήση στο endpoint.url σας)Το μυστικό webhook σε επίπεδο οργανισμού (το ίδιο με το παλαιού τύπου webhook με ένα URL) — όχι μυστικό ανά τελικό σημείο

Αποθηκεύστε το μυστικό στον διαχειριστή μυστικών ή σε μεταβλητή περιβάλλοντος — μην το υποβάλετε ποτέ σε commit.

Επαλήθευση κλήσεων εργαλείων

Όταν ο πράκτορας καλεί απευθείας ένα από τα εργαλεία συναρτήσεών σας (το εργαλείο έχει ένα endpoint), το αίτημα περιλαμβάνει αυτές τις κεφαλίδες ThunderPhone μαζί με τις ρυθμισμένες endpoint.headers:

  • X-ThunderPhone-Call-ID — το αριθμητικό αναγνωριστικό της ενεργής κλήσης.
  • X-ThunderPhone-Signature-V2 — η παραπάνω υπογραφή με χρονική σήμανση, με κλειδί το μυστικό webhook σε επίπεδο οργανισμού.
  • X-ThunderPhone-Signature — η παλαιού τύπου υπογραφή μόνο για το σώμα, με το ίδιο κλειδί.

Οι τηλεφωνικές κλήσεις περιλαμβάνουν επίσης τα X-ThunderPhone-From-Number, X-ThunderPhone-To-Number και X-ThunderPhone-Call-Direction (λεπτομέρειες). Όπως κάθε κεφαλίδα, δεν καλύπτονται από καμία από τις δύο υπογραφές.

Κάθε αίτημα εργαλείου υπογράφεται, ακόμη και αν ο οργανισμός σας δεν έχει διαμορφώσει ποτέ το παλαιό webhook: το ThunderPhone δημιουργεί αυτόματα το μυστικό του οργανισμού. Διαβάστε το από GET /v1/webhook.

Ένα στοιχείο διαφέρει από τα webhook: τα εργαλεία GET / DELETE δεν έχουν σώμα. Τα ορίσματα μεταφέρονται ως παράμετροι ερωτήματος. Η υπογραφή V2 τα καλύπτει μέσω της διαδρομής και του ερωτήματος, ενώ το πεδίο σώματος είναι κενό. Επαληθεύστε χρησιμοποιώντας την ακατέργαστη συμβολοσειρά ερωτήματος: η ανάλυση των παραμέτρων και η δημιουργία νέας συμβολοσειράς ερωτήματος μπορεί να αλλάξει τη σειρά ή την κωδικοποίησή τους. Η παλαιά κεφαλίδα υπογράφει την κενή ακολουθία byte.

@app.api_route("/tools/search-appointments", methods=["GET", "POST"])
async def tool(request: Request):
    body = await request.body()  # b"" for GET/DELETE tools
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=ORG_WEBHOOK_SECRET,
        method=request.method,
        path=raw_path_and_query(request),
        body=body,
    ):
        raise HTTPException(status_code=401)
    call_id = request.headers.get("X-ThunderPhone-Call-ID", "")
    args = json.loads(body) if body else dict(request.query_params)
    ...

Στο Express, ένας αναλυτής σώματος αφήνει το req.body ως κενό αντικείμενο σε ένα GET, οπότε περάστε Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0).

Η δρομολόγηση εργαλείων σε λειτουργία webhook (εργαλεία χωρίς endpoint, που παραδίδονται στο webhook του οργανισμού σας ως telephony.tool / web.tool) είναι ένα συνηθισμένο υπογεγραμμένο webhook — εφαρμόζεται η παραπάνω τυπική διαδικασία. Δείτε τα Εργαλεία συναρτήσεων για τις δύο μορφές αιτημάτων.

Παλαιότερη υπογραφή: X-ThunderPhone-Signature

Η αρχική κεφαλίδα είναι το δεκαεξαδικό HMAC-SHA256 μόνο του ακατέργαστου σώματος, με το ίδιο μυστικό. Δεν περιέχει χρονική σήμανση, επομένως οποιοσδήποτε καταγράψει ένα υπογεγραμμένο αίτημα μπορεί να το επαναλάβει. Εξακολουθεί να αποστέλλεται σε κάθε αίτημα όσο οι ενσωματώσεις μεταβαίνουν στη V2.

  1. Διαβάστε το ακατέργαστο σώμα του αιτήματος — τα ακριβή byte που σας στείλαμε.
  2. Υπολογίστε το hmac_sha256(secret, body).hexdigest().
  3. Συγκρίνετε σε σταθερό χρόνο με το X-ThunderPhone-Signature.

Υπογράφουμε ακριβώς τα byte που μεταδίδουμε. Αυτά τα byte είναι επίσης η κανονική σειριοποίηση JSON του ωφέλιμου φορτίου — κλειδιά ταξινομημένα αλφαβητικά, συμπαγείς διαχωριστές (, και : χωρίς κενά), UTF-8. Αν το framework σας εκθέτει μόνο αναλυμένο JSON, επανασειριοποιήστε το κανονικά και υπολογίστε HMAC για αυτό:

# Equivalent to hashing the raw body:
import json
canonical = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")

Προτιμήστε το ακατέργαστο σώμα — είναι ένα βήμα λιγότερο και δεν επηρεάζεται από ιδιομορφίες επαναμετατροπής αριθμών JSON σε ορισμένες γλώσσες. Το ίδιο ισχύει για το πεδίο σώματος της V2.

Python
import hashlib
import hmac
 
 
def verify(body: bytes, signature: str, secret: str) -> bool:
    """Constant-time HMAC-SHA256 verification."""
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")
Node.js
import crypto from "node:crypto";
 
export function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (!signature || expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}
Go
package webhook
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
 
func Verify(body []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}
Ruby
require "openssl"
 
def verify(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  Rack::Utils.secure_compare(expected, signature.to_s)
end

Συνήθη προβλήματα

Απόκλιση ρολογιού

Το παράθυρο των 5 λεπτών μετράται με βάση το ρολόι του διακομιστή σας. Διατηρήστε το συγχρονισμένο με NTP· ένα ρολόι που αποκλίνει περισσότερο από 5 λεπτά απορρίπτει κάθε αίτημα.

Ένας διακομιστής μεσολάβησης ξαναγράφει τη διαδρομή

Η υπογεγραμμένη διαδρομή είναι εκείνη που ζητήσαμε: η διαδρομή του URL που ρυθμίσατε στο ThunderPhone. Αν ένας αντίστροφος διακομιστής μεσολάβησης ή μια πύλη API αφαιρεί ή προσθέτει ένα πρόθεμα πριν η εφαρμογή σας λάβει το αίτημα, ανασυνθέστε τη διαδρομή που στείλαμε (για παράδειγμα, προσθέστε ξανά το πρόθεμα) πριν από την επαλήθευση.

Επανασειριοποίηση με προεπιλεγμένη μορφοποίηση

Η ανάλυση του σώματος και η εκ νέου εξαγωγή του με τις προεπιλογές της βιβλιοθήκης JSON σας (κενά μετά τα , / :, κλειδιά με σειρά εισαγωγής) παράγει διαφορετικά byte και καταστρέφει το HMAC. Επαληθεύστε το ακατέργαστο σώμα — ή αν πρέπει να το επανασειριοποιήσετε, αντιστοιχίστε ακριβώς την κανονική μορφή μας: ταξινομημένα κλειδιά, συμπαγείς διαχωριστές, UTF-8.

Το framework αναλύει αυτόματα το JSON

Το middleware express.json() του Express καταναλώνει τη ροή του σώματος και χάνετε τα ακατέργαστα byte. Χρησιμοποιήστε express.raw() ειδικά στη διαδρομή webhook ή αποθηκεύστε προσωρινά το ακατέργαστο σώμα σε ένα προ-middleware. Το ίδιο ισχύει για NestJS / Koa — ελέγξτε την τεκμηρίωσή τους για το «ακατέργαστο σώμα».

Σύγκριση μη ασφαλής ως προς τον χρόνο

Τα expected === signature σε JS ή expected == signature σε Python είναι συγκρίσεις μεταβλητού χρόνου. Χρησιμοποιήστε crypto.timingSafeEqual ή hmac.compare_digest αντίστοιχα. Η διαφορά στην απόδοση είναι μηδενική.

Λανθασμένο μυστικό για τελικά σημεία εργαλείων

Οι απευθείας κλήσεις τελικών σημείων εργαλείων υπογράφονται με το μυστικό webhook σε επίπεδο οργανισμού (GET /v1/webhook) — όχι με οποιοδήποτε μυστικό ανά τελικό σημείο από το /v1/developer/webhook-endpoints. Χρησιμοποιήστε ξανά το ίδιο βοηθητικό, αλλά βεβαιωθείτε ότι του παρέχετε το μυστικό του οργανισμού στις διαδρομές εργαλείων.

Παράμετροι ερωτήματος σε εργαλεία GET/DELETE

Το V2 υπογράφει τη συμβολοσειρά ερωτήματος ακριβώς όπως στάλθηκε. Η κεφαλίδα παλαιού τύπου υπογράφει το κενό σώμα και ποτέ τη συμβολοσειρά ερωτήματος, επομένως ο κατακερματισμός του URL για την κεφαλίδα παλαιού τύπου δεν θα ταιριάξει ποτέ.

Διπλότυπα εντός του παραθύρου

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

Μη επιστροφή 401 σε ασυμφωνία

Η επιστροφή 200 όταν η επαλήθευση αποτυγχάνει καθιστά τον χειριστή στόχο επανάληψης. Να απαντάτε πάντα με κωδικό εκτός 2xx αν η επαλήθευση αποτύχει.


Επόμενα βήματα