Telm은 모더레이션 이벤트를 여러분의 서버로 실시간 푸시할 수 있습니다. 엔드포인트를 등록하고, 수신할 이벤트를 선택하면, Telm이 각 이벤트마다 서명된 POST를 보냅니다. 모든 전달에는 엔드포인트 시크릿으로 검증하는 HMAC-SHA256 서명이 담깁니다. 실패한 전달은 일정에 따라 재시도되며, 영구적으로 도달 불가능한 엔드포인트는 자동으로 비활성화됩니다.
1이벤트 엔벨로프
모든 웹훅은 공통 엔벨로프에 담긴 JSON 본문을 가진 HTTP POST입니다. 엔벨로프에는 id(중복 제거를 위한 고유 전달 식별자), type(이벤트 이름), created_at 타임스탬프, 이벤트가 속한 group_id, 그리고 이벤트 유형에 따라 형태가 달라지는 data 객체가 있습니다.
id는 실제 이벤트에 대해 결정적이므로, 같은 이벤트가 두 번 전달되면 — 예를 들어 재시도 후 — 두 번 모두 같은 id를 받습니다. X-Telm-Delivery 헤더(이 id를 그대로 반영)를 멱등성 키로 사용해 핸들러가 각 이벤트를 한 번만 처리하게 하세요.
- 엔벨로프 필드: id, type, created_at, group_id, data.
- type은 아래 카탈로그의 이벤트 이름 중 하나입니다.
- data는 이벤트별 필드를 담습니다.
- 재시도를 중복 제거하려면 id(및 X-Telm-Delivery 헤더)를 사용하세요.
2이벤트 카탈로그
엔드포인트를 카탈로그의 임의 부분집합에 구독시킵니다. spam.detected는 엔진이 메시지를 스팸으로 플래그할 때 발생합니다. message.suspicious는 모니터링 모드에서, 엔진이 조치했을 법하지만 메시지를 섀도 채점만 했을 때 발생합니다. 멤버 이벤트는 사람이 들어오고, 나가고, 처벌받는 것을 다룹니다.
ping 이벤트는 특별합니다. 구독 가능한 카탈로그의 일부가 아니며, 엔드포인트에 대해 테스트 전달을 트리거할 때만 전송됩니다. 그래서 수신기와 서명 검사가 처음부터 끝까지 작동하는지 확인할 수 있습니다.
- spam.detected — 메시지가 스팸으로 분류됨.
- message.suspicious — 섀도(모니터링 모드) 감지.
- user.banned, user.kicked, user.muted — 모더레이션 조치가 적용됨.
- user.joined, user.left — 멤버가 그룹에 들어오거나 나감.
- ping — 수동 테스트 이벤트로, 실제 활동으로는 결코 발생하지 않음.
3이벤트별 페이로드 필드
spam.detected와 message.suspicious의 경우, data 객체는 message_id, user_id, username, 메시지 텍스트(매우 긴 메시지는 잘림), 취해진 action, category, reason, 감지된 언어, confidence 점수를 담습니다. message.suspicious는 추가로 섀도 score를 담습니다.
멤버 이벤트(user.joined, user.left, user.banned, user.kicked, user.muted)의 경우, data 객체는 user_id, username, first_name, 선택적 message_id, 그리고 해당하는 경우 reason을 담습니다. 하나의 근본 이벤트가 두 개 이상의 웹훅을 만들 수 있습니다. 차단을 유발한 스팸 메시지는 spam.detected와 user.banned 둘 다로 전달됩니다.
- 스팸 이벤트: message_id, user_id, username, text, action, category, reason, language, confidence(message.suspicious는 score 추가).
- 멤버 이벤트: user_id, username, first_name, message_id, reason.
- 하나의 사건이 여러 이벤트를 낼 수 있습니다. user_id와 group_id로 상관 지으세요.
4HMAC 서명 검증하기
각 전달은 서명되어 있어, 그것이 정말 Telm에서 왔으며 변조되지 않았음을 확신할 수 있습니다. 엔드포인트를 생성할 때 엔드포인트 시크릿(whsec_로 시작)을 단 한 번 받습니다. 그것을 보관해 들어오는 모든 요청을 검증하는 데 사용하세요.
검증하려면, X-Telm-Timestamp 헤더 값을 가져와 점 하나를 붙인 다음, 정확한 원시 요청 본문을 이어 붙이고, 엔드포인트 시크릿을 키로 사용해 그 문자열의 HMAC-SHA256을 계산하세요. 결과를 16진수로 인코딩하고 v1= 접두사를 붙이면 X-Telm-Signature 헤더와 일치해야 합니다. 상수 시간 비교로 비교하고, 리플레이를 막기 위해 타임스탬프가 몇 분(5분이 좋은 기준)보다 오래되었으면 요청을 거부하세요.
- X-Telm-Event — 이벤트 유형.
- X-Telm-Delivery — 전달 id(멱등성 키).
- X-Telm-Timestamp — 유닉스 초, 리플레이 방지를 위해 서명됨.
- X-Telm-Signature — v1= 다음에 타임스탬프, 점 하나, 원시 본문의 16진수 HMAC-SHA256.
5전달, 재시도, 자동 비활성화
전달은 엔드포인트가 2xx 상태로 응답할 때에만 성공으로 간주됩니다. 그 밖의 것 — 2xx가 아닌 코드, 타임아웃, 연결 오류 — 은 실패로 처리되어 고정된 일정으로 재시도됩니다. 즉시, 그다음 1분 후, 5분, 30분, 2시간, 6시간 후로, 전달이 실패로 종료되기까지 대략 8시간 반에 걸쳐 여섯 번 시도합니다.
엔드포인트가 계속 실패하면 — 3일 동안 성공 전달 없이 최소 20회 연속 실패 — Telm이 자동으로 비활성화해 죽은 URL로의 전송을 멈춥니다. 수신기가 다시 정상이 되면 대시보드에서 재활성화할 수 있습니다.
- 성공 = HTTP 2xx. 빠르게(약 10초 이내) 응답하고 무거운 작업은 비동기로 처리하세요.
- 재시도 일정: 즉시, +1분, +5분, +30분, +2시간, +6시간(여섯 번 시도).
- 72시간 내 성공 없이 20회 연속 실패하면 자동 비활성화됩니다.
- 웹훅 등록에는 Pro 요금제 이상이 필요합니다.