{"title":"Webhooks API","slug":"webhooks","category":"api","summary":"메모리, 채팅, 작업 이벤트에 대한 HTTP 콜백 등록 — 데이터 변경 시 알림을 받습니다.","audience":["human","llm"],"tags":["api","webhooks","automation","events"],"difficulty":"intermediate","updated":"2026-06-27","word_count":175,"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":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# Webhooks API\n\n웹훅을 사용하면 Synapse에서 이벤트가 발생할 때 HTTP 콜백을 받을 수\n있습니다. 외부 자동화 트리거, 알림 전송, 또는 다른 시스템으로의 동기화에\n적합합니다.\n\n## 엔드포인트\n\n### POST /webhooks\n\n새 웹훅을 등록합니다.\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\n응답:\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\n현재 마인드의 모든 웹훅을 나열합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks\n```\n\n### GET /webhooks/:id\n\n단일 웹훅을 가져옵니다.\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\n웹훅을 업데이트합니다 (URL, 이벤트, 시크릿, 또는 활성화 플래그).\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\n웹훅을 삭제합니다.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n## 이벤트 유형\n\n| 패턴 | 발생 시점 |\n|---------|------------|\n| `memory.*` | 모든 메모리 이벤트 |\n| `memory.store` | 새 메모리 저장 |\n| `memory.update` | 메모리 업데이트 |\n| `memory.delete` | 메모리 삭제 |\n| `chat.*` | 모든 채팅 이벤트 |\n| `chat.message_received` | 사람이 보낸 새 메시지 |\n| `task.*` | 모든 작업 이벤트 |\n| `task.created` | 새 작업 생성 |\n| `task.completed` | 작업 완료 표시 |\n| `*` | 모든 이벤트 |\n\n## 웹훅 페이로드\n\n이벤트가 발생하면 Synapse가 귀하의 URL로 POST합니다:\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## 서명 검증\n\n`secret`을 설정하면 Synapse가 각 페이로드를 HMAC-SHA256으로 서명합니다:\n\n```\nX-Synapse-Signature: sha256=\n```\n\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## 패턴: 실시간 동기화\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## 다음 단계\n\n- [Cron 및 Scheduler](/docs/api/cron)\n- [웹훅 자동화 가이드](/docs/guides/webhook-automation)\n","content_html":"

Webhooks API

\n

웹훅을 사용하면 Synapse에서 이벤트가 발생할 때 HTTP 콜백을 받을 수\n있습니다. 외부 자동화 트리거, 알림 전송, 또는 다른 시스템으로의 동기화에\n적합합니다.

\n

엔드포인트

\n

POST /webhooks

\n

새 웹훅을 등록합니다.

\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  }'

응답:

\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

현재 마인드의 모든 웹훅을 나열합니다.

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

GET /webhooks/:id

\n

단일 웹훅을 가져옵니다.

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

PUT /webhooks/:id

\n

웹훅을 업데이트합니다 (URL, 이벤트, 시크릿, 또는 활성화 플래그).

\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

웹훅을 삭제합니다.

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

이벤트 유형

\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
패턴발생 시점
memory.*모든 메모리 이벤트
memory.store새 메모리 저장
memory.update메모리 업데이트
memory.delete메모리 삭제
chat.*모든 채팅 이벤트
chat.message_received사람이 보낸 새 메시지
task.*모든 작업 이벤트
task.created새 작업 생성
task.completed작업 완료 표시
*모든 이벤트
\n

웹훅 페이로드

\n

이벤트가 발생하면 Synapse가 귀하의 URL로 POST합니다:

\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

secret을 설정하면 Synapse가 각 페이로드를 HMAC-SHA256으로 서명합니다:

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

핸들러에서 검증:

\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)

패턴: 실시간 동기화

\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","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"]}