Operations

Verifikasi tanda tangan webhook

Setiap permintaan webhook dan alat yang dikirim ThunderPhone ditandatangani. Verifikasi tanda tangan sekali menggunakan panduan di sini, lalu gunakan kembali pemeriksaan yang sama pada setiap endpoint yang Anda jalankan.

Setiap permintaan yang kami kirim ke server Anda — pengiriman webhook dan pemanggilan endpoint alat — membawa tanda tangan HMAC-SHA256 di header X-ThunderPhone-Signature. Lakukan verifikasi dengan benar sekali, lalu gunakan helper yang sama di setiap handler.

Algoritme#

1. Baca body permintaan mentah — byte persis yang kami POST kepada Anda.
2. Hitung hmac_sha256(secret, body).hexdigest().
3. Bandingkan dalam waktu konstan dengan X-ThunderPhone-Signature. (Perbandingan string naif membocorkan informasi waktu.)

Kami menandatangani byte persis yang kami kirimkan, sehingga memverifikasi body mentah selalu berfungsi. Byte tersebut juga merupakan serialisasi JSON kanonis dari payload — kunci diurutkan secara alfabetis, pemisah ringkas (, dan : tanpa spasi), UTF-8. Ini memberi Anda resep kedua yang sepenuhnya setara ketika framework Anda hanya menyediakan JSON yang sudah diurai: serialisasikan ulang secara kanonis dan lakukan HMAC terhadapnya.

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

Utamakan body mentah — langkahnya lebih sedikit dan kebal terhadap keunikan round-trip angka JSON dalam beberapa bahasa.

Rahasia yang mana?#

Simpan rahasia di pengelola rahasia atau variabel environment Anda — jangan pernah melakukan commit.

Implementasi referensi#

Keempatnya memverifikasi body permintaan mentah:

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

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),
  );
}

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))
}

require "openssl"
 
def verify(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  Rack::Utils.secure_compare(expected, signature.to_s)
end

Integrasi khusus framework#

from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
 
@app.post("/thunderphone-webhook")
async def hook(request: Request):
    body = await request.body()           # raw bytes, NOT request.json()
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify(body, sig, SECRET):
        raise HTTPException(status_code=401)
 
    import json
    event = json.loads(body)
    # … dispatch on event["type"] …
    return {"ok": True}

import express from "express";
 
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 sig = req.header("X-ThunderPhone-Signature") || "";
    if (!verify(req.body, sig, process.env.WEBHOOK_SECRET)) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
    // … dispatch on event.type …
    res.sendStatus(204);
  },
);

import json
 
from django.http import JsonResponse, HttpResponseForbidden
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
 
 
@csrf_exempt
@require_POST
def hook(request):
    body = request.body  # raw bytes
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify(body, sig, SECRET):
        return HttpResponseForbidden("invalid signature")
    event = json.loads(body)
    # … dispatch on event["type"] …
    return JsonResponse({"ok": True})

Memverifikasi panggilan alat#

Saat agen memanggil salah satu alat fungsi Anda secara langsung (alat tersebut memiliki endpoint), permintaan membawa dua header ThunderPhone bersama endpoint.headers yang Anda konfigurasi:

• X-ThunderPhone-Call-ID — ID numerik panggilan aktif.
• X-ThunderPhone-Signature — HMAC-SHA256, menggunakan rahasia webhook tingkat organisasi Anda sebagai kunci, atas byte isi permintaan yang persis sama.

Helper verify() yang sama dapat digunakan tanpa perubahan, dengan dua hal berikut:

1. Alat GET / DELETE tidak memiliki isi. Argumen dikirim sebagai parameter kueri, dan tanda tangan dihitung atas string byte kosong — jadi verify(b"", sig, secret) (Python) atau verify(Buffer.alloc(0), sig, secret) (Node). Jangan hash string kueri.
2. Organisasi tanpa webhook lama yang dikonfigurasi tidak memiliki rahasia organisasi. Dalam kasus tersebut, panggilan alat hanya membawa X-ThunderPhone-Call-ID dan tidak ada header tanda tangan. Konfigurasikan webhook lama (PUT /v1/webhook) untuk mendapatkan rahasia penandatanganan, atau autentikasi panggilan alat dengan header Anda sendiri melalui endpoint.headers.

@app.post("/tools/search-appointments")
async def tool(request: Request):
    body = await request.body()  # b"" for GET/DELETE tools
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    call_id = request.headers.get("X-ThunderPhone-Call-ID", "")
    if not verify(body, sig, ORG_WEBHOOK_SECRET):
        raise HTTPException(status_code=401)
    args = json.loads(body)
    ...

Pengiriman alat dalam mode webhook (alat tanpa endpoint, dikirimkan ke webhook organisasi Anda sebagai telephony.tool / web.tool) adalah webhook bertanda tangan biasa — resep standar di atas berlaku. Lihat Alat Fungsi untuk kedua bentuk permintaan.

Kesalahan umum#

Langkah berikutnya#