Webhooks

نظرة عامة على Webhooks

كيف يقدّم ThunderPhone الأحداث في الوقت الفعلي، وكيفية التحقق من التوقيعات، ومقارنة نماذج التسليم القديمة والقائمة على نقاط النهاية.

يرسل ThunderPhone طلبات HTTP POST إلى خادمك عند حدوث أمور أثناء مكالمة — بدء مكالمة واردة، وانتهاء مكالمة، واكتمال تشغيل تقييم، وإطلاق تنبيه، وغير ذلك. يوجد نموذجان للتسليم:

تُسلَّم أنواع الأحداث العشرة كلها في كتالوج الأحداث عبر نقاط نهاية webhook. تُرسل أحداث دورة حياة المكالمة الستة (telephony.incoming وtelephony.complete وtelephony.tool و web.incoming وweb.complete وweb.tool) أيضًا إلى webhook القديم ذي عنوان URL الواحد — إذا كان لديك عنوان URL قديم ونقطة نهاية مطابقة، فستتلقى الحدث عبر كلا المسارين. يوجد السلوك المعطِّل (تبادل إعداد telephony.incoming / web.incoming ووضع webhook الخاص بإرسال الأدوات) حصريًا في المسار القديم؛ أما كل عملية تسليم إلى نقطة نهاية فهي إشعار إرسال دون انتظار.

تنسيق الحمولة#

تكون عمليات التسليم إلى نقاط النهاية كائن 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. أمثلة التنسيق الجميل في هذه الوثائق مخصّصة لسهولة القراءة فقط.

راجع كتالوج الأحداث للحصول على القائمة الكاملة لأنواع الأحداث وحقول الحمولة.

التحقق من التوقيع#

يحمل كل طلب توقيع HMAC-SHA256 على النص الخام لجسم الطلب في الترويسة X-ThunderPhone-Signature. مفتاح التوقيع هو secret الخاص بنقطة النهاية (أو secret الخاص بخطاف الويب على مستوى مؤسستك لعمليات التسليم القديمة).

الخطوات#

1. اقرأ جسم الطلب الخام قبل أي تحليل.
2. احسب hmac_sha256(secret, body).hexdigest().
3. قارنه في وقت ثابت بترويسة X-ThunderPhone-Signature.

نوقّع البايتات التي نرسلها بالضبط، وهذه البايتات هي تمثيل JSON القياسي (مفاتيح مرتبة وفواصل مضغوطة). لذلك يعمل التحقق باستخدام الجسم الخام دائمًا — وإذا كان إطار عملك لا يزوّدك إلا بـ JSON محلل، فإن إعادة تسلسله بمفاتيح مرتبة وفواصل مضغوطة تنتج البايتات المطابقة. كلا الطريقتين مغطاتان في دليل التحقق.

import hmac
import hashlib
 
def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
# Example Flask handler
from flask import Flask, request, abort
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    body = request.get_data()
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify_signature(body, sig, WEBHOOK_SECRET):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import crypto from "node:crypto";
import express from "express";
 
function verifySignature(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),
  );
}
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("X-ThunderPhone-Signature") || "";
    if (!verifySignature(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);
  },
);

دلالات التسليم#

تنطبق هذه الدلالات على عمليات التسليم إلى نقاط النهاية. يمثل الويب هوك القديم ذو عنوان URL الواحد محاولة متزامنة واحدة دون إعادات محاولة.

الاختيار بين الويب هوك القديم والويب هوك المستند إلى نقاط النهاية#

ينبغي لعمليات التكامل الجديدة استهلاك الأحداث عبر الويب هوك المستند إلى نقاط النهاية. احتفظ بعنوان URL قديم (أو أضفه) فقط إذا كنت تضبط المكالمات بشكل ديناميكي عند وقت الرد أو تستخدم إرسال الأدوات في وضع الويب هوك — إذ إن عمليات تبادل الطلبات والاستجابات هذه تعمل فقط عبر المسار القديم.

ذو صلة#