웹훅 설정

봇에 하트가 오거나 초대 신청이 들어오면 한카리가 제작자의 서버로 알려 줘요. 주소와 받을 이벤트는 Hankari Devs의 봇 관리 > 연동 > 웹훅에서 정해요. 봇 소유자와 '개발 도구' 권한을 받은 공동 제작자가 바꿀 수 있어요.

설정 순서#

1. 받을 서버에 POST를 받는 주소를 하나 만들어요.
2. 연동 화면에 주소를 적고 '테스트 전송'으로 요청이 닿는지 확인해요.
3. 받을 이벤트를 고르고 저장해요. 처음 저장하면 서명 키가 한 번 보여요.
4. 서명 키를 서버에 넣고, 받은 요청마다 서명을 확인해요.

주소 규칙#

• https://로 시작하는 주소만 받아요. 500자까지 쓸 수 있어요.
• 주소에 아이디·비밀번호를 넣을 수 없어요.
• localhost, 사설망 IP, hankari.dev처럼 인터넷 밖이거나 한카리 자신을 가리키는 주소는 막아요. 한카리 서버가 대신 요청을 보내는 거라서요.
• 리다이렉트는 따라가지 않아요. 주소가 옮겨 갔다면 새 주소를 저장해 주세요.

받을 이벤트#

처음에는 heart만 켜져 있어요. 이벤트마다 본문 모양은 하트 이벤트와 초대 이벤트에 있어요.

서명 키#

• 주소를 처음 저장하면 whsec_로 시작하는 서명 키를 만들어 딱 한 번 보여 줘요. 그 뒤로는 끝 네 글자만 보여요.
• 키를 잃어버렸거나 새어 나갔으면 '다시 발급'을 눌러요. 그 순간부터 새 키로 서명하니, 서버의 키도 바로 바꿔 주세요.

테스트 전송#

'테스트 전송'은 지금 입력칸에 적힌 주소로 test 이벤트를 한 번 보내고 결과를 바로 보여 줘요. 저장하기 전에도 보낼 수 있어서, 서버가 요청을 받는지 먼저 확인할 수 있어요. 테스트는 다시 보내지 않고, 봇마다 1분에 10번까지 보낼 수 있어요.

전송 기록#

연동 화면 아래 '최근 웹훅 전송 기록'에 봇마다 최근 50건이 남아요. 이벤트, 결과, 응답 코드, 응답 시간, 보낸 시각을 보여 주고, 한 줄을 펼치면 시도 횟수, 보낸 주소, 전송 ID, 응답 본문 앞부분을 볼 수 있어요. 실패한 전송은 '다시 보내기'로 같은 전송 ID 그대로 다시 보낼 수 있어요.

5초 안에 답이 없거나 연결이 안 되거나 5xx·429로 답하면 1초 뒤, 그다음 4초 뒤에 다시 보내요(최대 3번). 그 밖의 4xx와 리다이렉트는 다시 보내지 않고 따라가지도 않아요.

받는 서버 체크리스트#

• 5초 안에 2xx로 답해 주세요. 오래 걸리는 일은 먼저 답하고 나서 따로 처리해요.
• 서명이 맞지 않는 요청은 버려요.
• 같은 X-Hankari-Delivery가 두 번 오면 다시 보낸 것이니 한 번만 처리해요.
• 이벤트가 일어난 순서대로 온다고 기대하지 마세요. 본문의 createdAt을 기준으로 삼아요.

웹훅 끄기#

주소 칸을 비우고 저장하면 더 보내지 않아요. 봇을 삭제해도 전송이 멈춰요.