{"title":"Webhooks API","slug":"webhooks","category":"api","summary":"Đăng ký HTTP callback cho sự kiện bộ nhớ, chat và tác vụ — nhận thông báo khi dữ liệu thay đổi.","audience":["human","llm"],"tags":["api","webhooks","automation","events"],"difficulty":"intermediate","updated":"2026-06-27","word_count":253,"read_minutes":1,"llm_context":"Auth: Mind Key\nRegister: POST /webhooks { url, events, secret? }\nList: GET /webhooks\nGet: GET /webhooks/:id\nUpdate: PUT /webhooks/:id { url?, events?, secret?, enabled? }\nDelete: DELETE /webhooks/:id\nEvents: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed\nSecret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header\nPattern: register webhook → receive POST → process event → call Synapse API\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Webhooks API\n\nWebhook cho phép bạn nhận HTTP callback khi sự kiện xảy ra trong Synapse. Hoàn\nhảo để kích hoạt tự động hóa bên ngoài, gửi thông báo hoặc đồng bộ với hệ thống\nkhác.\n\n## Các endpoint\n\n### POST /webhooks\n\nĐăng ký webhook mới.\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.*\",\n \"secret\": \"my-hmac-secret-min-8-chars\"\n }'\n```\n\nPhản hồi:\n\n```json\n{\n \"id\": \"wh_001\",\n \"url\": \"https://my-app.com/webhook\",\n \"events\": [\"memory.*\"],\n \"enabled\": true,\n \"created_at\": \"2026-06-27T...\"\n}\n```\n\n### GET /webhooks\n\nLiệt kê tất cả webhook cho mind hiện tại.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks\n```\n\n### GET /webhooks/:id\n\nLấy một webhook đơn lẻ.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n### PUT /webhooks/:id\n\nCập nhật webhook (URL, sự kiện, secret hoặc cờ enabled).\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/webhooks/wh_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"enabled\": false}'\n```\n\n### DELETE /webhooks/:id\n\nXóa một webhook.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n## Loại sự kiện\n\n| Mẫu | Kích hoạt khi |\n|---------|------------|\n| `memory.*` | Bất kỳ sự kiện bộ nhớ nào |\n| `memory.store` | Bộ nhớ mới được lưu |\n| `memory.update` | Bộ nhớ được cập nhật |\n| `memory.delete` | Bộ nhớ bị xóa |\n| `chat.*` | Bất kỳ sự kiện chat nào |\n| `chat.message_received` | Tin nhắn mới từ con người |\n| `task.*` | Bất kỳ sự kiện tác vụ nào |\n| `task.created` | Tác vụ mới được tạo |\n| `task.completed` | Tác vụ được đánh dấu đã xong |\n| `*` | Tất cả sự kiện |\n\n## Payload Webhook\n\nKhi sự kiện kích hoạt, Synapse POST đến URL của bạn:\n\n```json\n{\n \"event\": \"memory.store\",\n \"timestamp\": \"2026-06-27T...\",\n \"mind_id\": \"m_xyz789\",\n \"data\": {\n \"id\": \"mem_001\",\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"Michael Schäfer\"\n }\n}\n```\n\n## Xác minh chữ ký\n\nNếu bạn đặt `secret`, Synapse ký mỗi payload bằng HMAC-SHA256:\n\n```\nX-Synapse-Signature: sha256=\n```\n\nXác minh trong trình xử lý của bạn:\n\n```python\nimport hmac, hashlib\n\ndef verify_signature(payload_body: bytes, signature: str, secret: str) -> bool:\n expected = hmac.new(\n secret.encode(),\n payload_body,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n## Mẫu: Đồng bộ thời gian thực\n\n```python\n# Your webhook handler\n@app.post(\"/webhook\")\nasync def handle_webhook(request):\n body = await request.body()\n signature = request.headers.get(\"X-Synapse-Signature\", \"\")\n if not verify_signature(body, signature, WEBHOOK_SECRET):\n return 401\n\n event = json.loads(body)\n if event[\"event\"] == \"memory.store\":\n # Sync to another system\n sync_to_external(event[\"data\"])\n elif event[\"event\"] == \"chat.message_received\":\n # Trigger agent wake-up\n notify_agent(event[\"data\"])\n```\n\n## Bước tiếp theo\n\n- [Cron & Scheduler](/docs/api/cron)\n- [Hướng dẫn tự động hóa Webhook](/docs/guides/webhook-automation)\n","content_html":"

Webhooks API

\n

Webhook cho phép bạn nhận HTTP callback khi sự kiện xảy ra trong Synapse. Hoàn\nhảo để kích hoạt tự động hóa bên ngoài, gửi thông báo hoặc đồng bộ với hệ thống\nkhác.

\n

Các endpoint

\n

POST /webhooks

\n

Đăng ký webhook mới.

\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.*",\n    "secret": "my-hmac-secret-min-8-chars"\n  }'

Phản hồi:

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

GET /webhooks

\n

Liệt kê tất cả webhook cho mind hiện tại.

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

GET /webhooks/:id

\n

Lấy một webhook đơn lẻ.

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

PUT /webhooks/:id

\n

Cập nhật webhook (URL, sự kiện, secret hoặc cờ enabled).

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

DELETE /webhooks/:id

\n

Xóa một webhook.

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

Loại sự kiệ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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MẫuKích hoạt khi
memory.*Bất kỳ sự kiện bộ nhớ nào
memory.storeBộ nhớ mới được lưu
memory.updateBộ nhớ được cập nhật
memory.deleteBộ nhớ bị xóa
chat.*Bất kỳ sự kiện chat nào
chat.message_receivedTin nhắn mới từ con người
task.*Bất kỳ sự kiện tác vụ nào
task.createdTác vụ mới được tạo
task.completedTác vụ được đánh dấu đã xong
*Tất cả sự kiện
\n

Payload Webhook

\n

Khi sự kiện kích hoạt, Synapse POST đến URL của bạn:

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

Xác minh chữ ký

\n

Nếu bạn đặt secret, Synapse ký mỗi payload bằng HMAC-SHA256:

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

Xác minh trong trình xử lý của bạn:

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

Mẫu: Đồng bộ thời gian thực

\n
# Your webhook handler\n@app.post("/webhook")\nasync def handle_webhook(request):\n    body = await request.body()\n    signature = request.headers.get("X-Synapse-Signature", "")\n    if not verify_signature(body, signature, WEBHOOK_SECRET):\n        return 401\n\n    event = json.loads(body)\n    if event["event"] == "memory.store":\n        # Sync to another system\n        sync_to_external(event["data"])\n    elif event["event"] == "chat.message_received":\n        # Trigger agent wake-up\n        notify_agent(event["data"])

Bước tiếp theo

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