{"title":"Tự động hóa Webhook","slug":"webhook-automation","category":"guides","summary":"Kích hoạt hệ thống bên ngoài khi bộ nhớ thay đổi — đồng bộ, thông báo, tự động hóa.","audience":["human","llm"],"tags":["guide","webhooks","automation","integration"],"difficulty":"intermediate","updated":"2026-06-27","word_count":400,"read_minutes":2,"lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Tự động hóa Webhook\n\nWebhook cho phép bạn kích hoạt hệ thống bên ngoài khi sự kiện Synapse kích\nhoạt. Hướng dẫn này bao phủ mẫu tự động hóa phổ biến.\n\n## Mẫu phổ biến\n\n### Mẫu 1: Thông báo khi bộ nhớ Critical\n\nGửi tin nhắn Slack khi bộ nhớ critical được lưu:\n\n```python\n# Webhook handler (your server)\n@app.post(\"/webhook\")\nasync def handle(request):\n payload = await request.json()\n \n # Verify signature\n if not verify_signature(payload, request.headers):\n return 401\n \n if payload[\"event\"] == \"memory.store\":\n memory = payload[\"data\"]\n if memory.get(\"priority\") == \"critical\":\n # Send Slack notification\n await slack.post(\n f\"🚨 Critical memory stored: {memory['key']}\\n{memory['content'][:200]}\"\n )\n \n return 200\n```\n\nĐăng ký webhook:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/webhooks \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://my-app.com/webhook\",\n \"events\": \"memory.store\",\n \"secret\": \"my-hmac-secret\"\n }'\n```\n\n### Mẫu 2: Đồng bộ với hệ thống bên ngoài\n\nĐồng bộ bộ nhớ với Notion, Obsidian hoặc bất kỳ KB bên ngoài:\n\n```python\n@app.post(\"/webhook\")\nasync def sync_to_notion(request):\n payload = await request.json()\n \n if payload[\"event\"] == \"memory.store\":\n memory = payload[\"data\"]\n # Create Notion page\n await notion.create_page(\n title=memory[\"key\"],\n content=memory[\"content\"],\n tags=memory.get(\"tags\", [])\n )\n \n elif payload[\"event\"] == \"memory.delete\":\n # Delete from Notion\n await notion.delete_page(memory_id=payload[\"data\"][\"id\"])\n \n return 200\n```\n\n### Mẫu 3: Kích hoạt CI/CD\n\nKích hoạt triển khai khi một bộ nhớ \"release\" được lưu:\n\n```python\n@app.post(\"/webhook\")\nasync def trigger_deploy(request):\n payload = await request.json()\n \n if payload[\"event\"] == \"memory.store\":\n memory = payload[\"data\"]\n if memory.get(\"key\", \"\").startswith(\"release_\"):\n # Trigger GitLab pipeline\n await gitlab.trigger_pipeline(\n project=\"synapse\",\n ref=\"main\",\n variables={\"RELEASE_MEMORY_ID\": memory[\"id\"]}\n )\n \n return 200\n```\n\n### Mẫu 4: Đánh thức Agent khi tin nhắn con người\n\nKích hoạt chạy LLM agent khi con người gửi tin nhắn chat:\n\n```python\n@app.post(\"/webhook\")\nasync def wake_agent(request):\n payload = await request.json()\n \n if payload[\"event\"] == \"chat.message_received\":\n message = payload[\"data\"]\n # Queue agent processing job\n await job_queue.enqueue(\n \"process_message\",\n message_id=message[\"id\"],\n content=message[\"content\"]\n )\n \n return 200\n```\n\n### Mẫu 5: Tổng hợp chỉ số\n\nTheo dõi tăng trưởng bộ nhớ, hoạt động chat, hoàn thành tác vụ:\n\n```python\n@app.post(\"/webhook\")\nasync def track_metrics(request):\n payload = await request.json()\n event = payload[\"event\"]\n \n metrics = {\n \"memory.store\": \"memories_stored_total\",\n \"memory.delete\": \"memories_deleted_total\",\n \"chat.message_received\": \"messages_received_total\",\n \"task.created\": \"tasks_created_total\",\n \"task.completed\": \"tasks_completed_total\",\n }\n \n if event in metrics:\n await prometheus.increment(metrics[event])\n \n return 200\n```\n\n## Xác minh chữ ký\n\nLuôn xác minh chữ ký webhook để ngăn giả mạo:\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_signature(payload_body: bytes, headers, secret: str) -> bool:\n signature = headers.get(\"X-Synapse-Signature\", \"\")\n if not signature.startswith(\"sha256=\"):\n return False\n \n expected = hmac.new(\n secret.encode(),\n payload_body,\n hashlib.sha256\n ).hexdigest()\n \n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n## Logic thử lại\n\nSynapse thử lại webhook thất bại với exponential backoff. Trình xử lý của bạn nên:\n\n1. **Trả 200 nhanh** — không làm công việc nặng đồng bộ\n2. **Xếp hàng công việc** — sử dụng hệ thống công việc nền\n3. **Idempotent** — cùng sự kiện có thể được gửi hai lần\n\n```python\n@app.post(\"/webhook\")\nasync def handle(request):\n payload = await request.json()\n # Queue for async processing\n await job_queue.enqueue(\"process_webhook\", payload)\n # Return immediately\n return 200\n```\n\n## Gỡ lỗi Webhook\n\n### Kiểm tra lịch sử gửi\n\nViệc gửi webhook được ghi nhật ký. Kiểm tra gửi gần đây của webhook:\n\n```bash\n# Get webhook details including recent deliveries\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n### Kiểm tra webhook thủ công\n\n```bash\n# Trigger a test event\ncurl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\"\n```\n\n### Vấn đề phổ biến\n\n| Vấn đề | Khắc phục |\n|-------|-----|\n| Phản hồi 4xx | Kiểm tra trình xử lý trả 200 |\n| Phản hồi 5xx | Lỗi server — kiểm tra nhật ký ứng dụng |\n| Timeout | Trả 200 nhanh, xếp hàng công việc async |\n| Gửi trùng lặp | Làm trình xử lý idempotent |\n| Chữ ký không khớp | Xác minh secret chính xác |\n\n## Thực hành tốt nhất\n\n> [!TIP]\n> - **Luôn xác minh chữ ký** — không bao giờ bỏ qua\n> - **Trả 200 nhanh** — không chặn Synapse\n> - **Idempotent** — xử lý gửi trùng lặp\n> - **Sử dụng sự kiện cụ thể** — `memory.store` không phải `*`\n> - **Giám sát gửi thất bại** — thiết lập cảnh báo\n\n## Bước tiếp theo\n\n- [Webhooks API](/docs/api/webhooks)\n- [Cron & Scheduler](/docs/api/cron)\n- [LLM Agent cố định](/docs/guides/persistent-llm-agent)\n","content_html":"

Tự động hóa Webhook

\n

Webhook cho phép bạn kích hoạt hệ thống bên ngoài khi sự kiện Synapse kích\nhoạt. Hướng dẫn này bao phủ mẫu tự động hóa phổ biến.

\n

Mẫu phổ biến

\n

Mẫu 1: Thông báo khi bộ nhớ Critical

\n

Gửi tin nhắn Slack khi bộ nhớ critical được lưu:

\n
# Webhook handler (your server)\n@app.post("/webhook")\nasync def handle(request):\n    payload = await request.json()\n    \n    # Verify signature\n    if not verify_signature(payload, request.headers):\n        return 401\n    \n    if payload["event"] == "memory.store":\n        memory = payload["data"]\n        if memory.get("priority") == "critical":\n            # Send Slack notification\n            await slack.post(\n                f"🚨 Critical memory stored: {memory['key']}\\n{memory['content'][:200]}"\n            )\n    \n    return 200

Đăng ký webhook:

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

Mẫu 2: Đồng bộ với hệ thống bên ngoài

\n

Đồng bộ bộ nhớ với Notion, Obsidian hoặc bất kỳ KB bên ngoài:

\n
@app.post("/webhook")\nasync def sync_to_notion(request):\n    payload = await request.json()\n    \n    if payload["event"] == "memory.store":\n        memory = payload["data"]\n        # Create Notion page\n        await notion.create_page(\n            title=memory["key"],\n            content=memory["content"],\n            tags=memory.get("tags", [])\n        )\n    \n    elif payload["event"] == "memory.delete":\n        # Delete from Notion\n        await notion.delete_page(memory_id=payload["data"]["id"])\n    \n    return 200

Mẫu 3: Kích hoạt CI/CD

\n

Kích hoạt triển khai khi một bộ nhớ "release" được lưu:

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

Mẫu 4: Đánh thức Agent khi tin nhắn con người

\n

Kích hoạt chạy LLM agent khi con người gửi tin nhắn chat:

\n
@app.post("/webhook")\nasync def wake_agent(request):\n    payload = await request.json()\n    \n    if payload["event"] == "chat.message_received":\n        message = payload["data"]\n        # Queue agent processing job\n        await job_queue.enqueue(\n            "process_message",\n            message_id=message["id"],\n            content=message["content"]\n        )\n    \n    return 200

Mẫu 5: Tổng hợp chỉ số

\n

Theo dõi tăng trưởng bộ nhớ, hoạt động chat, hoàn thành tác vụ:

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

Xác minh chữ ký

\n

Luôn xác minh chữ ký webhook để ngăn giả mạo:

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

Logic thử lại

\n

Synapse thử lại webhook thất bại với exponential backoff. Trình xử lý của bạn nên:

\n
    \n
  1. Trả 200 nhanh — không làm công việc nặng đồng bộ
    2. \n
  2. Xếp hàng công việc — sử dụng hệ thống công việc nền
    3. \n
  3. Idempotent — cùng sự kiện có thể được gửi hai lần
    4. \n
\n
@app.post("/webhook")\nasync def handle(request):\n    payload = await request.json()\n    # Queue for async processing\n    await job_queue.enqueue("process_webhook", payload)\n    # Return immediately\n    return 200

Gỡ lỗi Webhook

\n

Kiểm tra lịch sử gửi

\n

Việc gửi webhook được ghi nhật ký. Kiểm tra gửi gần đây của webhook:

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

Kiểm tra webhook thủ công

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

Vấn đề phổ biến

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Vấn đềKhắc phục
Phản hồi 4xxKiểm tra trình xử lý trả 200
Phản hồi 5xxLỗi server — kiểm tra nhật ký ứng dụng
TimeoutTrả 200 nhanh, xếp hàng công việc async
Gửi trùng lặpLàm trình xử lý idempotent
Chữ ký không khớpXác minh secret chính xác
\n

Thực hành tốt nhất

\n

Bước tiếp theo

\n\n","urls":{"html":"/docs/guides/webhook-automation","text":"/docs/guides/webhook-automation?format=text","json":"/docs/guides/webhook-automation?format=json","llm":"/docs/guides/webhook-automation?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}