# Webhook स्वचालन

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

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

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

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

```python
# 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 रजिस्टर करें:

```bash
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 में सिंक करें:

```python
@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" मेमोरी स्टोर होने पर डिप्लॉयमेंट ट्रिगर करें:

```python
@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 एजेंट रन ट्रिगर करें:

```python
@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: समग्र मेट्रिक्स

मेमोरी वृद्धि, चैट गतिविधि, कार्य पूर्णता ट्रैक करें:

```python
@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 सिग्नेचर सत्यापित करें:

```python
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 बनें** — समान इवेंट दो बार डिलीवर हो सकता है

```python
@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 की हालिया डिलीवरी जाँचें:

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

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

```bash
# 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 सही है |

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

> [!TIP]
> - **हमेशा सिग्नेचर सत्यापित करें** — इसे कभी न छोड़ें
> - **तेज़ी से 200 लौटाएँ** — Synapse को ब्लॉक न करें
> - **Idempotent बनें** — डुप्लिकेट डिलीवरी संभालें
> - **विशिष्ट इवेंट्स का उपयोग करें** — `memory.store`, `*` नहीं
> - **डिलीवरी विफलता मॉनिटर करें** — अलर्टिंग सेटअप करें

## अगले कदम

- [Webhooks API](/docs/api/webhooks)
- [Cron & Scheduler](/docs/api/cron)
- [Persistent LLM Agent](/docs/guides/persistent-llm-agent)