إرسال الأحداث إلى أنظمتك عبر خطافات الويب

أبلغ خادمك حين تتغير التذاكر أو الرسائل أو العملاء أو التقييمات، وتحقق من التوقيع، وتابع الإرسالات وإعادة المحاولات.

الويب
في هذه الصفحة
  1. إضافة خطاف ويب
  2. الأحداث
  3. التحقق من التوقيع
  4. الردود وإعادة المحاولات والسجل

يرسل خطاف الويب رسالة إلى خادمك كلما حدث شيء في مكتب المساعدة، ليتفاعل معه نظام آخر: كتحديث نظام إدارة العملاء، أو النشر في قناة، أو بدء سير عمل. ويدير المسؤولون خطافات الويب.

إضافة خطاف ويب

  1. انتقل إلى الإعدادات ثم خطافات الويب واختر إضافة خطاف ويب.
  2. أدخل الاسم والرابط الخاص بالخادم المستقبِل. يجب أن يستعمل https، وتُرفض العناوين الخاصة والمحلية وعناوين البيانات الوصفية السحابية.
  3. علّم الأحداث التي تريدها.
  4. احفظ، ثم انسخ سر التوقيع، فلن يُعرض مرة أخرى.

يمكن أن يضم مكتب المساعدة 20 خطاف ويب على الأكثر. اختر إرسال اختبار لتسليم حدث ping فورًا ورؤية رد خادمك.

الأحداث

الحدث متى يُرسَل
ticket.created عند إنشاء تذكرة من أي قناة
ticket.updated عند تغيّر حقول تذكرة، مع قائمة التغييرات
ticket.solved عند تحويل تذكرة إلى محلولة
message.created عند إضافة رسالة إلى تذكرة
customer.created عند إنشاء عميل جديد
csat.received عندما يجيب عميل عن استبيان الرضا

كل إرسال طلب POST بمحتوى JSON:

{
  "id": "6f1c2a52-8d0e-4a7b-9f3e-2b1d7c4e9a10",
  "event": "ticket.solved",
  "created_at": "2026-11-07T09:30:00Z",
  "workspace_id": "0b6e…",
  "data": {
    "ticket": {
      "number": 42,
      "subject": "Order not delivered",
      "status": "solved",
      "priority": "normal",
      "requester": { "name": "Ana Haddad", "email": "ana@example.com" }
    }
  }
}

ويرافقه الترويسان X-Aoun-Event (الحدث) وX-Aoun-Delivery (هذا الإرسال). ويبقى id في المحتوى كما هو إذا أُعيد الإرسال، فاستعمله لتجاهل حدث عالجته من قبل.

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

يحمل كل إرسال الترويسة X-Aoun-Signature: t=<الوقت>,v1=<التوقيع>. والتوقيع هو HMAC-SHA256 بالنظام الست عشري للوقت ثم نقطة ثم المحتوى الخام، ومفتاحه سر التوقيع. تحقق منه على المحتوى الخام قبل قراءة JSON، وقارن بزمن ثابت، وارفض الأوقات الأقدم من 5 دقائق.

Node.js (Express):

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/aoun-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get('X-Aoun-Signature') || '').split(',').map((p) => p.split('=')),
  );
  const expected = crypto
    .createHmac('sha256', process.env.AOUN_WEBHOOK_SECRET)
    .update(`${sig.t}.`)
    .update(req.body)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const valid = fresh && typeof sig.v1 === 'string' && sig.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body);
  // event.event, event.data …
  res.status(204).end();
});

PHP:

$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_AOUN_SIGNATURE'] ?? ''), $sig);
$t = $sig['t'] ?? '';
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('AOUN_WEBHOOK_SECRET'));

if (abs(time() - (int) $t) > 300 || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// $event['event'], $event['data'] …
http_response_code(204);

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/aoun-webhook")
def aoun_webhook():
    body = request.get_data()
    header = request.headers.get("X-Aoun-Signature", "")
    sig = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = sig.get("t", "0")
    expected = hmac.new(
        os.environ["AOUN_WEBHOOK_SECRET"].encode(),
        t.encode() + b"." + body,
        hashlib.sha256,
    ).hexdigest()
    if not t.isdigit() or abs(time.time() - int(t)) > 300 or not hmac.compare_digest(expected, sig.get("v1", "")):
        abort(401)
    event = request.get_json()
    # event["event"], event["data"] …
    return "", 204

الردود وإعادة المحاولات والسجل

أجب بأي حالة 2xx خلال 10 ثوانٍ، وإلا يعيد عون المحاولة بعد 1 و5 و30 دقيقة، ثم بعد 2 و6 و12 ساعة، قبل أن يعلّم الإرسال بـ فشل. وبعد 20 إرسالًا فاشلًا متتاليًا يُوقَف خطاف الويب، فأصلح الخادم المستقبِل ثم أعد تفعيله.

اختر الإرسالات لخطاف ما لترى آخر 30 يومًا: الحالة (تم التسليم أو بانتظار إعادة المحاولة أو فشل) وعدد المحاولات ورد خادمك والمحتوى المرسل. ويضع إعادة الإرسال أي إرسال في الطابور من جديد.

يستبدل سر جديد سر التوقيع فورًا، فحدّث الخادم المستقبِل بالسر الجديد.