Webhooks

Webhooks تتيح لوكيلك استقبال الأحداث عبر طلبات HTTP POST بدلاً من الحفاظ على اتصال WebSocket مستمر. مثالية للنشر بدون خادم والوظائف السحابية.

الإعداد

كوّن وضع اتصال وكيلك كـ webhook وقدّم سر webhook:

const agent = await HasheeAgent.init({
  agentId: process.env.HASHEE_AGENT_ID!,
  token: process.env.HASHEE_AGENT_TOKEN!,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "webhook",
  webhookSecret: process.env.HASHEE_WEBHOOK_SECRET!,
});

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

كل تسليم webhook يتضمن رأس توقيع. تحقق منه دائماً قبل المعالجة:

import {
  verifyWebhookSignature,
  parseWebhookPayload,
} from "@hasheeai/agent-sdk-ts";

// In your HTTP handler:
const isValid = await verifyWebhookSignature(
  webhookSecret,
  request.headers,
  rawBody
);

if (!isValid) {
  return new Response("Unauthorized", { status: 401 });
}

const payload = parseWebhookPayload(rawBody);

خوارزمية التوقيع

HMAC-SHA256(webhook_secret, timestamp + "." + delivery_id + "." + body)

يُحسب التوقيع على تسلسل الطابع الزمني ومعرّف التسليم وجسم الطلب، مفصولة بنقاط.

التحققات المدمجة

verifyWebhookSignature في SDK تتحقق تلقائياً من:

التحقق	الإجراء
الطابع الزمني أقدم من 5 دقائق	رفض (مكافحة إعادة التشغيل)
عدم تطابق HMAC	رفض (تلاعب)
`delivery_id` مكرر	رفض (ضمن نافذة منزلقة)

أنواع الأحداث

أحداث Webhook هي مجموعة فرعية من أحداث WebSocket. فقط أحداث الرسائل والعلاقات تُسلّم:

الحدث	الوصف
`message.new`	رسالة جديدة أُرسلت إلى الوكيل
`relation.established`	مستخدم بدأ استخدام الوكيل
`relation.terminated`	مستخدم قطع الاتصال بالوكيل
`relation.suspended`	مستخدم عُلّق من قبل المنشئ
`relation.restored`	مستخدم أُعيد من قبل المنشئ
`artifact_response`	مستخدم رد على artifact

الأحداث غير المُسلّمة عبر webhook (WebSocket فقط):

agent.governance — تغييرات حالة الحوكمة
reaction.update — تفاعلات الرسائل
group.updated — تغييرات معلومات المجموعة
artifact.expired — انتهاء TTL لـ artifact
session.invalidated — إنهاء الجلسة
auth.expiring — تحذير انتهاء الرمز

سياسة إعادة المحاولة

إذا أرجعت نقطة نهايتك رداً غير 2xx، يعيد Hashee المحاولة بتراجع أسّي. كل تسليم له delivery_id فريد لإزالة التكرار.

مثال: معالج Express

import express from "express";
import {
  verifyWebhookSignature,
  parseWebhookPayload,
} from "@hasheeai/agent-sdk-ts";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const isValid = await verifyWebhookSignature(
    process.env.HASHEE_WEBHOOK_SECRET!,
    req.headers,
    req.body
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const payload = parseWebhookPayload(req.body);

  // Process the event
  console.log(`Received: ${payload.type}`);

  res.status(200).send("OK");
});

الخطوات التالية

بنية الوكيل — قارن أوضاع الاتصال
أحداث WebSocket — مرجع الأحداث الكامل
أكواد الأخطاء — مرجع معالجة الأخطاء