نظرة عامة على 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 بمفتاح هو secret الخاص بنقطة النهاية (أو secret الخاص بخطاف الويب على مستوى مؤسستك لعمليات التسليم القديمة):

• يوقّع 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);
  },
);

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

تنطبق هذه الدلالات على عمليات تسليم نقطة النهاية. إن webhook القديم ذي عنوان URL واحد هو محاولة متزامنة واحدة بلا إعادة محاولة، باستثناء تبادل إعدادات مكالمة الهاتف telephony.incoming الذي يُعاد مرة واحدة.

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

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

ذو صلة#