# 웹훅 자동화
SUMMARY: 메모리 변경 시 외부 시스템 트리거 — 동기화, 알림, 자동화.

웹훅 자동화
웹훅을 사용하면 Synapse 이벤트가 발생할 때 외부 시스템을 트리거할 수
있습니다. 이 가이드는 일반적인 자동화 패턴을 다룹니다.
일반적인 패턴
패턴 1: 중요 메모리 알림
중요 메모리가 저장될 때 Slack 메시지를 전송:
[CODE BLOCK]
웹훅 등록:
[CODE BLOCK]
패턴 2: 외부 시스템 동기화
메모리를 Notion, Obsidian 또는 외부 KB에 동기화:
[CODE BLOCK]
패턴 3: CI/CD 트리거
"release" 메모리가 저장될 때 배포 트리거:
[CODE BLOCK]
패턴 4: 사람의 메시지 시 에이전트 깨우기
사람이 채팅 메시지를 보낼 때 LLM 에이전트 실행 트리거:
[CODE BLOCK]
패턴 5: 메트릭 집계
메모리 증가, 채팅 활동, 작업 완료 추적:
[CODE BLOCK]
서명 검증
스푸핑을 방지하기 위해 항상 웹훅 서명을 검증하십시오:
[CODE BLOCK]
재시도 로직
Synapse는 실패한 웹훅을 지수 백오프로 재시도합니다. 귀하의 핸들러는
다음을 수행해야 합니다:
1. 빠르게 200 반환 — 동기적으로 무거운 작업을 하지 마십시오
2. 작업 큐잉 — 백그라운드 작업 시스템 사용
3. 멱등성 — 동일한 이벤트가 두 번 전달될 수 있음
[CODE BLOCK]
웹훅 디버깅
전송 기록 확인
웹훅 전송은 기록됩니다. 웹훅의 최근 전송을 확인하십시오:
[CODE BLOCK]
수동 웹훅 테스트
[CODE BLOCK]
일반적인 문제
| 문제 | 해결 |
|-------|-----|
| 4xx 응답 | 핸들러가 200을 반환하는지 확인 |
| 5xx 응답 | 서버 오류 — 앱 로그 확인 |
| 시간 초과 | 200을 빨리 반환, 작업을 비동기로 큐잉 |
| 중복 전송 | 핸들러를 멱등으로 만들기 |
| 서명 불일치 | 시크릿이 올바른지 확인 |
모범 사례
> [!TIP]
> - 항상 서명 검증 — 이를 건너뛰지 마십시오
> - 빠르게 200 반환 — Synapse를 차단하지 마십시오
> - 멱등성 — 중복 전송 처리
> - 특정 이벤트 사용 — 가 아닌 
> - 전송 실패 모니터링 — 알림 설정
다음 단계
- Webhooks API
- Cron 및 Scheduler
- 영구 LLM 에이전트