웹훅 — 여러분의 시스템에 실시간 모더레이션 이벤트를

1웹훅이 하는 일

API를 폴링하는 대신 URL을 등록하면, 그룹에서 무언가 일어날 때마다 Telm이 서명된 HTTP POST를 그리로 보냅니다. 이것이 모더레이션 이벤트를 여러분 자신의 시스템 — 대시보드, 데이터 웨어하우스, 알림 채널 — 에 실시간으로 가져오는 방법입니다.

웹훅 엔드포인트는 API를 통해 관리합니다: URL을 등록하고, 구독할 이벤트를 고르고, 선택적으로 특정 그룹으로 한정하고, 테스트 핑을 보내고, 최근 전송 로그를 읽습니다.

2왜 밀어 주는 것이 폴링을 이기는가

새 이벤트를 찾으려고 기록 엔드포인트를 타이머로 호출할 수도 있지만, 그것은 지연을 더하고, 할당량을 쓰고, 무언가 일어나는 바로 그 순간을 놓칠 수 있습니다. 웹훅은 모델을 뒤집습니다: Telm이 이벤트가 발생하는 즉시 알려 주므로 여러분의 시스템이 몇 초 안에 반응합니다.

전형적인 용도로는 차단을 여러분 자신의 관리 도구로 반영하기, 레이드가 탐지되면 팀 채널에 알리기, 탐지를 분석으로 스트리밍하기, 또는 멤버가 참여하거나 이탈할 때 워크플로를 트리거하기 등이 있습니다.

• 실시간: 다음 폴링 때가 아니라 이벤트가 발생할 때 알게 됩니다.
• 효율적: 일일 할당량을 갉아먹는 반복 읽기가 없습니다.
• 완전함: 전송이 재시도되므로, 여러분 쪽의 짧은 장애가 이벤트를 잃지 않습니다.

3구독할 수 있는 이벤트

구독 가능한 이벤트 유형은 일곱 가지로, 스팸 판정, 처벌, 멤버십 변경을 다룹니다. 하나의 모더레이션된 메시지가 둘 이상의 이벤트를 낼 수 있습니다 — 차단으로 끝나는 스팸 메시지는 spam.detected와 user.banned를 모두 발생시킵니다.

• spam.detected — 엔진이 메시지를 스팸으로 표시했습니다.
• message.suspicious — 점수가 있는 섀도(모니터링 모드) 탐지입니다.
• user.banned — 멤버가 차단되었습니다.
• user.kicked — 멤버가 내보내졌습니다.
• user.muted — 멤버가 음소거되었습니다.
• user.joined — 멤버가 그룹에 참여했습니다.
• user.left — 멤버가 그룹을 떠났습니다.

4페이로드 봉투

모든 전송은 작고 안정적인 최상위 필드 집합과 그 안의 이벤트별 data 객체를 담은 JSON 봉투입니다. 세부 사항을 파싱하기 전에 유형과 시각으로 라우팅할 수 있습니다.

• id — 고유한 전송 id입니다. 같은 이벤트의 재전송은 같은 id를 재사용하며, 이것이 중복을 제거하는 방법입니다.
• type — 이벤트 유형으로, 위 일곱 가지 중 하나입니다.
• created_at — 이벤트가 발생한 시각으로, RFC3339 UTC 형식입니다.
• group_id — 이벤트가 속한 그룹입니다(해당하는 경우).
• data — 이벤트별 객체입니다: 스팸 이벤트의 메시지 및 판정 세부 정보, 멤버십 이벤트의 멤버 세부 정보.

5전송이 정말 Telm에서 온 것인지 검증하기

모든 전송은 서명되어 있어, 여러분의 서버가 요청이 진짜로 Telm에서 왔고 전송 중에 변조되지 않았음을 확인할 수 있습니다. 페이로드를 신뢰하기 전에 서명을 검증하고, 일치하지 않는 것은 무엇이든 거부하세요.

서명은 타임스탬프와 원본 요청 본문의 HMAC-SHA256이며, 여러분의 엔드포인트 서명 비밀 값으로 키가 지정됩니다. 검증하려면 타임스탬프 헤더와 받은 정확한 바이트에 대해 HMAC을 다시 계산하고, 이를 서명 헤더와 비교하세요.

• X-Telm-Signature — 서명으로, v1 뒤에 타임스탬프와 본문을 이은 것의 16진수 HMAC-SHA256이 붙는 형식입니다.
• X-Telm-Timestamp — 서명되는 유닉스 초 단위 타임스탬프로, 오래되거나 재생된 전송을 거부할 수 있습니다.
• X-Telm-Event — 이벤트 유형이며, X-Telm-Delivery — 중복 제거를 위한 전송 id입니다.
• 서명 비밀 값은 엔드포인트를 만들 때 한 번만 표시되며 whsec_로 시작합니다. 안전하게 저장하세요. 전송이 진짜임을 증명하는 유일한 것입니다.

6신뢰할 수 있고 중복이 제거된 전송

전송은 최소 한 번(at-least-once)입니다: Telm은 이벤트가 여러분에게 도달하도록 보장하며, 이는 같은 이벤트가 가끔 두 번 도착할 수 있다는 뜻입니다. 모든 재전송이 같은 전송 id를 재사용하므로, 처리한 id를 저장하고 반복을 건너뛰어 중복을 제거하세요.

여러분의 엔드포인트에 도달할 수 없거나 오류를 반환하면, 전송이 고정된 일정에 따라 재시도됩니다 — 대략 1분, 5분, 30분, 2시간, 6시간 후로, 약 8시간 30분에 걸쳐 최대 6회입니다. 계속 실패하는 엔드포인트는 양쪽을 보호하기 위해 자동으로 비활성화되고 소유자에게 통지됩니다.

• 2xx 상태로 빠르게 응답하세요. 확인한 뒤 무거운 작업은 비동기로 처리하세요.
• 전송 id로 중복을 제거하세요 — 절대 페이로드 내용으로 하지 마세요.
• 72시간 창 안에서 한 번도 성공 없이 약 스무 번 연속 실패하는 엔드포인트는 자동 비활성화됩니다. 서버가 정상이 되면 다시 활성화하세요.

7엔드포인트 관리와 로그 읽기

웹훅 엔드포인트는 API를 통해 등록하고, 편집하고, 제거합니다. 엔드포인트를 만들면 서명 비밀 값을 정확히 한 번 받고, 구독할 이벤트를 고르고, 선택적으로 특정 그룹으로 범위를 한정합니다. 테스트 호출은 서명된 핑을 보내므로, 실제 트래픽이 시작되기 전에 검증이 작동하는지 확인할 수 있습니다.

각 엔드포인트는 무엇이 언제 보내졌고 성공했는지 되돌아 볼 수 있는 전송 로그를 유지합니다 — 다음 실시간 이벤트를 기다리지 않고 수신기를 디버깅하는 데 유용합니다.

• 엔드포인트를 만들고 whsec_ 비밀 값을 즉시 복사하세요.
• 테스트 핑을 보내 서명 검사를 처음부터 끝까지 검증하세요.
• 엔드포인트를 한 그룹으로 한정하거나, 여러분이 관리하는 모든 그룹에 열어 두세요.
• 전송 로그를 읽어 최근 시도와 그 결과를 살펴보세요.

8모범 사례와 흔한 실수

견고한 수신기는 가장 흔한 문제를 막는 몇 가지 규칙을 따릅니다.

• 원본 본문 바이트에 대해 서명을 검증하세요 — 먼저 JSON으로 파싱하고 다시 직렬화하면 바이트가 바뀌어 검사가 깨질 수 있습니다.
• 2xx를 빠르게 반환하고 나중에 처리하세요. 느린 핸들러는 타임아웃과 불필요한 재시도를 유발합니다.
• 재전송된 이벤트가 중복 집계되지 않도록 처리를 멱등하게 만드세요.
• 공개적으로 도달 가능한 URL에서 HTTPS를 쓰세요. Telm은 내부 및 사설 주소를 차단하고 리다이렉트를 따르지 않습니다.
• whsec_ 비밀 값을 로그와 클라이언트 코드에서 빼내세요.