أتمتة الـ Webhooks

تتيح لك الـ Webhooks تشغيل الأنظمة الخارجية عند إطلاق أحداث Synapse. يغطي هذا الدليل أنماط أتمتة شائعة.

الأنماط الشائعة

النمط 1: إشعار عند ذاكرة حرجة

أرسل رسالة Slack عند تخزين ذاكرة حرجة:

# معالج الـ webhook (خادمك)
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    
    # تحقق من التوقيع
    if not verify_signature(payload, request.headers):
        return 401
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        if memory.get("priority") == "critical":
            # أرسل إشعار Slack
            await slack.post(
                f"🚨 Critical memory stored: {memory['key']}\n{memory['content'][:200]}"
            )
    
    return 200

سجّل الـ webhook:

curl -X POST https://synapse.schaefer.zone/webhooks \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-app.com/webhook",
    "events": "memory.store",
    "secret": "my-hmac-secret"
  }'

النمط 2: مزامنة إلى نظام خارجي

زامن الذكريات إلى Notion، Obsidian، أو أي KB خارجي:

@app.post("/webhook")
async def sync_to_notion(request):
    payload = await request.json()
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        # أنشئ صفحة Notion
        await notion.create_page(
            title=memory["key"],
            content=memory["content"],
            tags=memory.get("tags", [])
        )
    
    elif payload["event"] == "memory.delete":
        # احذف من Notion
        await notion.delete_page(memory_id=payload["data"]["id"])
    
    return 200

النمط 3: تشغيل CI/CD

شغّل نشرًا عند تخزين ذاكرة "release":

@app.post("/webhook")
async def trigger_deploy(request):
    payload = await request.json()
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        if memory.get("key", "").startswith("release_"):
            # شغّل pipeline GitLab
            await gitlab.trigger_pipeline(
                project="synapse",
                ref="main",
                variables={"RELEASE_MEMORY_ID": memory["id"]}
            )
    
    return 200

النمط 4: إيقاظ الوكيل عند رسالة الإنسان

شغّل تشغيل وكيل LLM عندما يرسل الإنسان رسالة دردشة:

@app.post("/webhook")
async def wake_agent(request):
    payload = await request.json()
    
    if payload["event"] == "chat.message_received":
        message = payload["data"]
        # أدرج مهمة معالجة الوكيل في الطابور
        await job_queue.enqueue(
            "process_message",
            message_id=message["id"],
            content=message["content"]
        )
    
    return 200

النمط 5: تجميع المقاييس

تتبع نمو الذاكرة، نشاط الدردشة، إكمال المهام:

@app.post("/webhook")
async def track_metrics(request):
    payload = await request.json()
    event = payload["event"]
    
    metrics = {
        "memory.store": "memories_stored_total",
        "memory.delete": "memories_deleted_total",
        "chat.message_received": "messages_received_total",
        "task.created": "tasks_created_total",
        "task.completed": "tasks_completed_total",
    }
    
    if event in metrics:
        await prometheus.increment(metrics[event])
    
    return 200

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

تحقق دائمًا من توقيعات الـ webhook لمنع الانتحال:

import hmac
import hashlib

def verify_signature(payload_body: bytes, headers, secret: str) -> bool:
    signature = headers.get("X-Synapse-Signature", "")
    if not signature.startswith("sha256="):
        return False
    
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(f"sha256={expected}", signature)

منطق إعادة المحاولة

يعيد Synapse محاولة الـ webhooks الفاشلة مع تراجع أُسي. يجب أن يفعل معالجك:

1. يُرجع 200 بسرعة — لا تفعل عملًا ثقيلًا تزامنيًا
2. أدرج العمل في الطابور — استخدم نظام مهام خلفي
3. كن idempotent — قد يُسلَّم نفس الحدث مرتين

@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    # أدرج للمعالجة غير المتزامنة
    await job_queue.enqueue("process_webhook", payload)
    # اعد فورًا
    return 200

تصحيح الـ Webhooks

تحقق من سجل التسليم

تُسجَّل تسليمات الـ webhook. تحقق من التسليمات الحديثة لـ webhook الخاص بك:

# احصل على تفاصيل الـ webhook بما في ذلك التسليمات الحديثة
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001

اختبر الـ webhook يدويًا

# شغّل حدث اختبار
curl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \
  -H "Authorization: Bearer YOUR_MIND_KEY"

مشكلات شائعة

المشكلة	الإصلاح
استجابات 4xx	تحقق أن معالجك يُرجع 200
استجابات 5xx	خطأ خادم — تحقق من سجلات تطبيقك
انتهاء المهلة	أرجع 200 بسرعة، أدرج العمل غير المتزامن
تسليمات مكررة	اجعل المعالج idempotent
عدم تطابق التوقيع	تحقق أن السر صحيح

أفضل الممارسات

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

• Webhooks API
• Cron والمجدول
• وكيل LLM الدائم