Webhooks API

تتيح لك الـ Webhooks استقبال استدعاءات HTTP عند وقوع أحداث في Synapse. مثالية لتشغيل الأتمتة الخارجية أو إرسال الإشعارات أو المزامنة مع أنظمة أخرى.

نقاط النهاية

POST /webhooks

تسجيل 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.*",
    "secret": "my-hmac-secret-min-8-chars"
  }'

الاستجابة:

{
  "id": "wh_001",
  "url": "https://my-app.com/webhook",
  "events": ["memory.*"],
  "enabled": true,
  "created_at": "2026-06-27T..."
}

GET /webhooks

قائمة بجميع الـ webhooks للعقل الحالي.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks

GET /webhooks/:id

الحصول على webhook واحد.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001

PUT /webhooks/:id

تحديث webhook (URL، الأحداث، السر، أو علم التمكين).

curl -X PUT https://synapse.schaefer.zone/webhooks/wh_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

DELETE /webhooks/:id

حذف webhook.

curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001

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

حمولة الـ Webhook

عند إطلاق حدث، يُرسل Synapse POST إلى عنوان URL الخاص بك:

{
  "event": "memory.store",
  "timestamp": "2026-06-27T...",
  "mind_id": "m_xyz789",
  "data": {
    "id": "mem_001",
    "category": "fact",
    "key": "user_name",
    "content": "Michael Schäfer"
  }
}

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

إذا عيّنت secret، يوقّع Synapse كل حمولة بـ HMAC-SHA256:

X-Synapse-Signature: sha256=<hex-hmac>

تحقق في معالجك:

import hmac, hashlib

def verify_signature(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

النمط: المزامنة اللحظية

# معالج الـ webhook الخاص بك
@app.post("/webhook")
async def handle_webhook(request):
    body = await request.body()
    signature = request.headers.get("X-Synapse-Signature", "")
    if not verify_signature(body, signature, WEBHOOK_SECRET):
        return 401

    event = json.loads(body)
    if event["event"] == "memory.store":
        # المزامنة إلى نظام آخر
        sync_to_external(event["data"])
    elif event["event"] == "chat.message_received":
        # تشغيل تنبيه الوكيل
        notify_agent(event["data"])

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

• Cron والمجدول
• دليل أتمتة الـ Webhooks