Webhook स्वचालन

Webhooks आपको Synapse इवेंट्स फायर होने पर बाहरी सिस्टम्स को ट्रिगर करने की सुविधा देते हैं। यह गाइड सामान्य स्वचालन पैटर्न को कवर करती है।

सामान्य पैटर्न

पैटर्न 1: महत्वपूर्ण मेमोरी पर सूचित करें

महत्वपूर्ण मेमोरी स्टोर होने पर Slack संदेश भेजें:

# Webhook handler (your server)
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    
    # Verify signature
    if not verify_signature(payload, request.headers):
        return 401
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        if memory.get("priority") == "critical":
            # Send Slack notification
            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"]
        # Create Notion page
        await notion.create_page(
            title=memory["key"],
            content=memory["content"],
            tags=memory.get("tags", [])
        )
    
    elif payload["event"] == "memory.delete":
        # Delete from 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_"):
            # Trigger GitLab pipeline
            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"]
        # Queue agent processing job
        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()
    # Queue for async processing
    await job_queue.enqueue("process_webhook", payload)
    # Return immediately
    return 200

Webhooks डिबग करना

डिलीवरी इतिहास जाँचें

Webhook डिलीवरी लॉग की जाती है। अपने webhook की हालिया डिलीवरी जाँचें:

# Get webhook details including recent deliveries
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001

Webhook मैन्युअली टेस्ट करें

# Trigger a test event
curl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \
  -H "Authorization: Bearer YOUR_MIND_KEY"

सामान्य समस्याएँ

समस्या	समाधान
4xx रिस्पॉन्स	जाँचें कि हैंडलर 200 लौटाता है
5xx रिस्पॉन्स	सर्वर त्रुटि — अपने ऐप लॉग जाँचें
Timeout	तेज़ी से 200 लौटाएँ, कार्य एसिंक कतारबद्ध करें
डुप्लिकेट डिलीवरी	हैंडलर को idempotent बनाएँ
सिग्नेचर मिसमैच	सत्यापित करें कि secret सही है

सर्वोत्तम अभ्यास

अगले कदम

• Webhooks API
• Cron & Scheduler
• Persistent LLM Agent