엔진에서 곧바로 나오는 일곱 가지 이벤트
엔드포인트별로 필요한 이벤트만 정확히 구독하세요 — 스팸 판정부터 멤버십 변경까지요.
spam.detectedmessage.suspicioususer.banneduser.kickeduser.muteduser.joineduser.left모든 이벤트는 간결한 JSON 봉투로 전달됩니다: id, type, created_at, group_id, 그리고 이벤트 데이터 — id는 재시도 사이에도 그대로 유지되므로, 중복 제거는 집합 조회 한 번이면 됩니다.
실제로 작동하는 그대로의 재시도 일정
약 여덟 시간에 걸친 여섯 번의 시도 — 여러분 쪽의 배포, 재시작, 완전한 장애를 견뎌내기에 충분합니다.
0즉시+1m+5m+30m+2h+6h마지막 시도믿고 구축할 수 있는 전달
최소 한 번 전달
모든 이벤트는 최소 한 번 전달됩니다. 여러분의 엔드포인트가 2xx로 확인하면 완료이고 — 그 외의 응답은 재시도 큐로 돌아갑니다.
중복 제거를 위한 안정적인 id
각 이벤트에는 재시도에도 살아남는 안정적인 id가 있습니다. 여러분 쪽의 중복 제거는 추정이 아니라 단 한 번의 조회입니다.
좀비 엔드포인트 없음
며칠 동안 실패하는 엔드포인트는 자동으로 비활성화되며 — 데이터에 조용한 공백이 생기는 대신 텔레그램 DM을 받습니다.
테스트 핑
클릭 한 번으로 보내는 테스트 이벤트, 실제와 똑같이 서명됩니다 — 단 하나의 실제 이벤트가 여기에 의존하기 전에 핸들러를 검증하세요.
들여다볼 수 있는 이력
엔드포인트별 전체 전달 이력: 모든 시도, 상태, 타임스탬프 — 수신기를 디버깅하는 데 추측이 개입할 일은 없습니다.
오직 HTTPS, 항상 서명
엔드포인트는 공개 HTTPS URL이어야 하며, 모든 페이로드에 서명이 붙습니다. 전송과 작성자 확인이 모두 보장됩니다.
모든 전달을 검증하세요
여러분 쪽에서는 세 줄 — 그러면 누구도 이벤트를 위조하거나 재전송할 수 없습니다.
# X-Telm-Signature: v1=<hex>
expected = hmac_sha256(secret, timestamp + "." + body)
valid = constant_time_eq("v1=" + hex(expected), header)폴링하지 말고, 푸시하세요
API를 폴링하면 여러분이 물어본 시점에 무슨 일이 있었는지 알 수 있지만, 웹훅은 그 일이 일어나는 순간을 알려줍니다. HTTPS 엔드포인트를 등록하고, 관심 있는 이벤트를 고르면, Telm은 그것들을 JSON으로 여러분의 서버에 밀어 넣기 시작합니다 — 스팸 물결, 차단, 가입 레이드 — 엔진이 조치를 취하는 바로 그 순간에요.
모든 전달에는 서명이 있습니다. X-Telm-Signature 헤더에는 엔드포인트의 시크릿으로 계산한 타임스탬프와 본문의 HMAC-SHA256이 담겨 있어, 여러분의 서버가 작성자와 신선도를 세 줄의 코드로 검증할 수 있습니다. 페이로드는 오직 HTTPS로만 전송됩니다.
전달은 수신 측이 다운되는 실제 인터넷 환경을 위해 설계되었습니다. 이벤트는 중복 제거를 위한 안정적인 id와 함께 최소 한 번 전달되며, 실패는 점점 늘어나는 간격으로 재시도됩니다 — 즉시, 그다음 1분과 5분 후, 30분 후, 2시간과 6시간 후에요. 며칠 동안 계속 실패하는 엔드포인트는 자동으로 비활성화되고, 조용한 공백 대신 그에 관한 텔레그램 메시지를 받게 됩니다.
모든 것을 들여다볼 수 있습니다: 실서비스 투입 전에 테스트 핑을 보내고, 파이프라인의 여러분 쪽을 디버깅해야 할 때면 언제든 전달 이력을 시도별로, 상태별로 살펴보세요.
자주 묻는 질문
이벤트가 정말 Telm에서 온 것인지 어떻게 검증하나요?
각 전달에는 X-Telm-Signature 헤더가 실려 있습니다: 엔드포인트의 시크릿으로 계산한 "timestamp.body"의 HMAC-SHA256입니다. 여러분 쪽에서 다시 계산해 상수 시간으로 비교하고, 재전송 공격을 배제하기 위해 몇 분보다 오래된 것은 거부하세요.
이벤트가 발생할 때 제 서버가 다운되어 있으면 어떻게 되나요?
Telm은 점점 늘어나는 일정으로 재시도합니다 — 즉시, 그다음 1분, 5분, 30분, 2시간, 6시간 후에요. 모든 2xx 응답은 전달 완료로 간주됩니다. 이벤트에는 안정적인 id가 실려 있어, 재시도가 여러분 시스템에서 중복이 되는 일은 없습니다.
고장 난 엔드포인트가 영원히 넘쳐날 수 있나요?
아니요. 사흘 동안 성공 없이 연속으로 스무 번쯤 실패하는 엔드포인트는 자동으로 비활성화되고, 여러분은 텔레그램 알림을 받습니다. 여러분 쪽을 고친 뒤 클릭 한 번으로 다시 활성화하세요.
실서비스 투입 전에 연동을 어떻게 테스트하나요?
대시보드나 API에서 아무 엔드포인트로든 테스트 핑을 보내세요 — 실제 이벤트와 똑같이 서명되어 도착합니다. 전달 이력에는 모든 시도가 상태와 함께 표시됩니다.
어떤 플랜에 웹훅이 포함되나요?
웹훅은 전체 API 패키지의 일부로, Pro와 Business 플랜에 포함됩니다.