# Автоматизація webhook-ів

Webhooks дозволяють запускати зовнішні системи, коли спрацьовують події Synapse.
Цей посібник охоплює поширені шаблони автоматизації.

## Поширені шаблони

### Шаблон 1: Сповіщення про критичний спогад

Надсилайте повідомлення в Slack, коли зберігається критичний спогад:

```python
# Обробник 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:

```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"]
        # Створити сторінку 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»:

```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_"):
            # Запустити pipeline GitLab
            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"]
        # Поставити в чергу завдання обробки агента
        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 повторює невдалі webhook-и з експоненційною затримкою. Ваш обробник має:

1. **Повернути 200 швидко** — не робіть важку роботу синхронно
2. **Ставити роботу в чергу** — використовуйте фонову систему завдань
3. **Бути ідемпотентним** — та сама подія може доставлятися двічі

```python
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    # Поставити в чергу для асинхронної обробки
    await job_queue.enqueue("process_webhook", payload)
    # Повернути негайно
    return 200
```

## Налагодження webhook-ів

### Перевірка історії доставок

Доставки webhook-ів логуються. Перевірте недавні доставки вашого webhook-а:

```bash
# Отримати деталі webhook, включаючи недавні доставки
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001
```

### Тест webhook вручну

```bash
# Запустити тестову подію
curl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \
  -H "Authorization: Bearer YOUR_MIND_KEY"
```

### Поширені проблеми

| Проблема | Виправлення |
|-------|-----|
| 4xx відповіді | Перевірте, що обробник повертає 200 |
| 5xx відповіді | Помилка сервера — перевірте логи додатку |
| Тайм-аут | Повертайте 200 швидко, ставте роботу в чергу асинхронно |
| Дубльовані доставки | Зробіть обробник ідемпотентним |
| Невідповідність підпису | Перевірте, що секрет правильний |

## Найкращі практики

> [!TIP]
> - **Завжди перевіряйте підписи** — ніколи не пропускайте це
> - **Повертайте 200 швидко** — не блокуйте Synapse
> - **Будьте ідемпотентними** — обробляйте дубльовані доставки
> - **Використовуйте специфічні події** — `memory.store`, а не `*`
> - **Моніторте збої доставки** — налаштуйте сповіщення

## Наступні кроки

- [Webhooks API](/docs/api/webhooks)
- [Cron та планувальник](/docs/api/cron)
- [Постійний LLM-агент](/docs/guides/persistent-llm-agent)