Webhook으로 Agent에게 이벤트 보내기
이 가이드를 마치면 외부 서비스의 event를 지정한 Agent 또는 Chat Room으로 보낼 수 있습니다. signing secret과 verifier가 설정된 Source에서는 서명 검증을 거칩니다.
시작하기 전에
- Webhook source와 rule을 만들 권한이 필요합니다.
- event를 받을 조직, Agent 또는 Room을 미리 정합니다.
- 외부 서비스에서 HTTPS Webhook URL과 signing secret을 설정할 수 있어야 합니다.
- event payload에 고객 데이터가 포함될 수 있으므로, 수신 대상과 playbook 내용을 최소 범위로 정합니다.
1. Playbook 만들기
- 웹훅 → 플레이북 → 플레이북 생성을 선택합니다.
- 이름과 내용을 입력합니다. 필요하면 미리보기 또는 분할로 Markdown 결과를 확인합니다.
- 하단 저장을 선택하고, 플레이북 목록에 새 항목이 보이는지 확인합니다.
Playbook은 source와 rule에 각각 연결할 수 있으며, event 메시지에 함께 추가됩니다.
예: “배포 실패 event를 받으면 영향 범위를 요약하고, 확정되지 않은 원인은 추측하지 말고 필요한 확인 항목을 나열하세요.”
2. Source 만들기
- 웹훅 → 소스 → 소스 생성을 열고 source type을 고른 뒤 다음 단계로 이동합니다.
- 이름과 대상 조직을 입력합니다.
- 필요하면 source 수준 Playbook, rate limit, secret 생성, signature 방식을 지정합니다.
- 소스 생성을 선택합니다.
- 마지막 Integration guide에서 Webhook URL과, 표시될 경우 signing secret의 복사 버튼을 각각 눌러 외부 서비스 설정에 등록합니다.
signing secret은 생성·재생성·rotation 때만 평문으로 표시될 수 있습니다. 문서나 Chat에 붙여 넣지 말고 조직의 비밀값 보관 절차에 따라 보관하세요.
3. Rule로 대상 정하기
- 웹훅 → 규칙 → 규칙 생성을 엽니다.
- 이름, 소스, 대상 유형을 고르고 필요한 event 조건을 추가합니다.
- 대상으로 Agent 또는 Room을 하나 이상 선택합니다.
- 같은 유형의 대상을 둘 이상 고르면 전체 전달(broadcast) 또는 round-robin 방식을 선택합니다.
- 필요하면 rule 수준 Playbook, cooldown, 시간당 제한을 설정합니다.
- 하단 규칙 생성을 선택하고 웹훅 목록에 새 규칙이 보이는지 확인합니다.
Source와 대상 Agent·Room은 같은 tenant 안에 있어야 합니다. 조직 단위 분리는 rule을 만드는 운영자가 대상 Agent·Room을 정확히 선택해 관리합니다.
4. 테스트와 확인
외부 서비스의 test event를 보낸 뒤 다음을 확인합니다.
- 웹훅 → 이벤트에 수신 event가 기록되는지
- Agent target이면 Cloud가 해당 Agent용 webhook Room으로 event를 전달하는지와 Agent가 실행 가능한 상태인지
- Room target이면 지정한 Room에 시스템 메시지가 나타나는지와 필요한 참여자가 있는지
Agent는 event의 source, rule, event ID, JSON payload, 연결된 Playbook 지침을 메시지로 받습니다.
중지·rotation·복구
- 새 event를 멈추려면 Source 또는 Rule을 inactive로 전환합니다.
- Secret이 노출됐다고 판단되면 Source에서 rotate 또는 regenerate하고 외부 서비스 설정도 즉시 바꿉니다.
- 삭제는 되돌릴 수 없을 수 있으므로 Source·Rule·Playbook 설정을 먼저 보관합니다.
- 현재 ingress에는 사용자 실행 replay endpoint나 자동 delivery retry가 확인되지 않았습니다. 실패 시 Event 기록, 대상 Room, Agent 상태를 확인한 뒤 외부 서비스를 통해 새 event를 보내야 할 수 있습니다.