웹훅은 새 멤버 가입이나 결제 도착처럼 커뮤니티에서 어떤 일이 일어날 때마다 Mateflow에서 직접 관리하는 URL로 HTTPS 요청을 보냅니다. 웹훅을 사용해 CRM, 이메일 도구, 자체 앱의 데이터를 동기화합니다. 웹훅은 관리자 → 설정 → 통합 → 웹훅에서 설정합니다.
사용 가능한 사람: 소유자와 관리자. · 위치: 웹(관리 콘솔). · 플랜: 웹훅 사용 여부와 만들 수 있는 개수는 플랫폼 플랜에 따라 다릅니다.
웹훅 엔드포인트 만들기
- 관리자 → 설정 → 통합으로 이동하여 웹훅 탭을 엽니다.
- 웹훅 추가를 클릭합니다.
- 이름(100자 미만)과 엔드포인트 URL을 입력합니다. URL은 HTTPS를 사용해야 합니다.
- 선택 사항이지만 권장합니다. 시크릿 (선택) 항목에서 생성 버튼(시크릿 생성)을 클릭하고 서버에서 사용할 시크릿을 복사합니다. 아래의 서명 섹션을 참고하세요.
- 이벤트에서 보낼 이벤트에 체크합니다. 카테고리 이름에 체크하면 해당 카테고리의 모든 이벤트가 선택됩니다.
- 웹훅이 이벤트를 받기 시작하도록 활성을 켜 둡니다.
- 웹훅 생성을 클릭합니다.
웹훅 추가 버튼에 업그레이드 안내가 표시되면 플랜에 웹훅이 포함되어 있지 않거나 플랜의 웹훅 한도에 도달한 것입니다. 플랜 사용량과 한도 확인하기를 참고하세요.
구독할 수 있는 웹훅 이벤트
| 카테고리 | 이벤트 |
|---|---|
| 멤버 | 멤버 가입, 역할 변경, 멤버 정지(차단 시에도 전송), 멤버 복구, 멤버 액세스 그룹 추가, 멤버 액세스 그룹 제거 |
| 콘텐츠 | 게시물 생성, 댓글 생성, 게시물 삭제, 댓글 삭제 |
| 결제 | 결제 수신, 결제 실패, 구독 생성, 구독 갱신, 구독 취소, 환불 발행 |
이전에 만든 웹훅에는 더 이상 제공되지 않는 이벤트가 표시될 수 있습니다. 이런 이벤트는 제거할 수 있지만 다시 추가할 수는 없습니다.
액세스 그룹 웹훅 이벤트의 작동 방식
멤버 액세스 그룹 추가와 멤버 액세스 그룹 제거(액세스 그룹의 이전 이름은 멤버 등급)는 멤버의 그룹이 실제로 변경될 때 발생합니다. 각 이벤트는 멤버 한 명과 그룹 하나를 다루며, 멤버의 사용자 이름과 이메일, 그룹 이름, 변경 원인(관리자, 구독, 초대, 기본 액세스 그룹, 그룹 삭제)을 포함합니다.
- 멤버 가입 전에는 액세스 그룹 이벤트가 전송되지 않습니다. 따라서 새 멤버가 가입할 때 받는 기본 그룹은 알리지 않으며, 멤버가 승인을 기다리는 동안의 변경도 알리지 않습니다.
- 액세스 그룹을 삭제하면 그 그룹을 가진 멤버마다 제거 이벤트가 하나씩 전송됩니다. 이 이벤트와 기본 그룹 설정으로 인한 이벤트는 몇 분 늦게 도착할 수 있습니다.
- 구독으로 부여되는 그룹을 제거하면 구독이 바로 그룹을 다시 추가하므로 제거 이벤트 다음에 추가 이벤트가 전송됩니다. 멤버의 액세스 그룹 추가 또는 제거하기를 참고하세요.
서명 시크릿으로 웹훅 서명 검증하기
웹훅에 시크릿이 있으면 Mateflow는 각 요청에 HMAC-SHA256으로 서명합니다. 서버는 이를 통해 요청이 Mateflow에서 왔고 변경되지 않았는지 확인할 수 있습니다(서명 검증). 각 요청에는 헤더 두 개가 포함됩니다.
X-Mateflow-Timestamp: 요청을 보낸 시각(Unix 초)입니다.X-Mateflow-Signature:sha256=뒤에 16진수로 인코딩한 서명이 붙습니다.
서버에서 요청을 검증하는 방법은 다음과 같습니다.
- JSON을 파싱하기 전에, 받은 그대로의 원시 요청 본문을 읽습니다.
- 서명 대상 문자열을 만듭니다.
X-Mateflow-Timestamp값, 마침표(.), 원시 본문 순서입니다. - 시크릿을 키로 사용해 이 문자열의 HMAC-SHA256을 계산하고 16진수로 인코딩합니다.
- 상수 시간 비교를 사용해
X-Mateflow-Signature에서sha256=뒤의 부분과 비교합니다. 다르면 요청을 거부합니다. - 선택 사항으로, 재전송 공격을 막기 위해 타임스탬프가 몇 분 이상 지난 요청을 거부합니다.
전환 기간 동안에는 요청의 X-Webhook-Secret 헤더에 시크릿 자체도 포함됩니다. 이 헤더에 의존하지 말고 서명을 검증하세요.
자동화 규칙의 Trigger webhook 액션에서 보내는 요청은 다르게 작동합니다. 서명되지 않으며, 규칙의 시크릿이 X-Webhook-Secret 헤더에 그대로 전송됩니다. 규칙으로 작업 자동화하기를 참고하세요.
저장한 후에는 시크릿이 숨겨집니다. 시크릿을 유지하려면 웹훅을 편집할 때 필드를 비워 둡니다. 시크릿을 교체하려면 새 시크릿을 생성하고 동시에 서버도 업데이트합니다.
웹훅 테스트, 일시 중지, 편집 또는 삭제하기
웹훅의 작업 메뉴에서 다음을 사용할 수 있습니다.
- 웹훅 테스트는 엔드포인트로 테스트 요청을 보냅니다.
- 비활성화는 웹훅을 삭제하지 않고 전송을 중지합니다. 활성화로 다시 켭니다.
- 편집은 이름, URL, 시크릿, 이벤트를 변경합니다.
- 삭제는 웹훅과 모든 전송 로그를 제거합니다. 되돌릴 수 없습니다.
목록에는 각 웹훅의 상태, 마지막 실행, 성공 및 실패 횟수가 표시됩니다. 최근 전송이 실패한 웹훅에는 오류 상태가 표시됩니다.
웹훅 전송 및 재시도 확인하기
전송 로그 탭을 열면 각 요청과 HTTP 상태, 소요 시간, 출처를 볼 수 있습니다. 상세 보기를 클릭하면 전체 요청 페이로드와 응답 본문이 표시됩니다. 전송 로그는 30일 동안 보관됩니다.
전송이 실패하면 Mateflow가 최대 3번까지 자동으로 재시도합니다. 직접 다시 보내는 버튼은 없습니다. 시도마다 별도의 행과 새 전송 ID가 생기지만 이벤트 ID는 그대로이므로, 이벤트 ID가 같은 행은 한 이벤트에 대한 시도입니다. 전송은 두 번 이상 도착하거나 순서가 바뀌어 도착할 수 있으므로 서버에서 이벤트 ID로 중복을 제거하세요. 페이로드 필드는 mateflow.com/developers의 개발자 문서를 참고하세요.
관련 문서
이 가이드가 도움이 되었나요?