발신 웹훅

현재 메인 버전: 소스 체크아웃을 사용하십시오. 0.7.0 휴대용 미리보기 버전은 이 기능이 구현되기 전의 버전입니다.

워크플로우 가이드 · 위키

선택한 작업 공간에서 [Open Integrations] → [Outgoing webhooks]를 선택합니다. HTTPS 수신자를 추가하고, 수집기/미디어/내보내기 이벤트를 선택한 다음, 선택 사항으로 새로운 관측 및 변경 사항에 대한 채팅을 선택합니다. 메시지 본문은 기본적으로 비활성화되어 있습니다. 발췌문 기능을 활성화하면 메시지 변경 이벤트에 최대 1,000자까지 추가되며, 텔레그램의 원본 필드 및 인증 정보는 절대 전송되지 않습니다.

HMAC 비밀 키를 수신자의 보호된 구성에 한 번만 복사해 두십시오. 이 키는 TgWitness의 볼트에 암호화되어 저장되며, 패널에서는 검색할 수 없습니다. 목적지를 삭제하고 다시 생성하여 키를 순환시키십시오. 채팅 내용이 없는 테스트 메시지를 합성 테스트 큐로 전송한 후, 전달 상태를 새로 고침하여 결과를 확인하십시오.

이 전송 기능은 Apprise와 함께 기존 알림 루프를 확장합니다. 이 기능은 워크스페이스의 외부 경로와 기존 비공개 수신처 제한 사항을 사용합니다. 직접적인 대체 경로나 리디렉션은 없습니다. URL에는 인증 정보, 쿼리 문자열 또는 프래그먼트가 포함되어서는 안 되며, 비공개 주소의 경우 패널 사용자가 우회할 수 없는 서버 수준의 네트워크 옵트인 설정이 필요합니다.

페이로드 및 서명#

스키마: tgwitness.webhook/1. 모든 페이로드에는 event_id, timestamp, workspace, type, synthetic 및 카운터가 포함됩니다. 저널 기반 이벤트에는 시퀀스와 해시가 포함됩니다. 전체 내보내기 완료 및 합성 테스트는 전달 이벤트이며, 임의로 생성된 서명된 저널 참조는 포함되지 않습니다. 텔레그램 삭제 알림과 missing_on_recheck는 별개의 유형으로 유지됩니다.

X-TgWitness-Signature 헤더는 t=UNIX_SECONDS,v1=HEX_HMAC_SHA256입니다. 표시된 비밀 키를 UTF-8 바이트로 사용하여 timestamp + "." + raw_request_body의 정확한 바이트에 대해 HMAC을 계산합니다. 본문을 파싱하거나 처리기 전에 상수 시간 내에 서명을 비교합니다. 현재 시계와 5분 이상 차이가 나는 타임스탬프는 거부합니다. 타임스탬프는 전달 시도가 있을 때마다 갱신됩니다.

event_id를 내구성 있는 저장소의 항등성 키로 사용하며, 부수 효과 발생 전에 원자적 고유성 제약 조건을 적용하십시오. 유효한 서명만으로는 최근 요청이 재전송되는 것을 방지할 수 없습니다. 처리된 ID는 최소한 전체 재시도 기간 동안 보관해야 하며, 수신자가 저장된 이벤트를 재처리할 수 있는 경우에는 더 오래 보관해야 합니다.

재시도#

전달 작업은 HTTP 요청 전에 안정적으로 대기열에 추가됩니다. 이 시스템은 ‘최소 1회(at-least-once)’ 세манти크를 사용합니다. 즉, 확인 응답이 누락되거나 시스템이 재시작될 경우, 동일한 ID를 가진 이벤트가 다시 전달될 수 있습니다. 지수적 백오프(exponential backoff) 방식을 적용하여 총 8회 시도하며, 시도는 15초부터 시작하여 최대 1시간까지 진행됩니다. 성공 여부는 2xx 응답으로 판단됩니다. 처리 한도에 도달한 작업은 가시적인 오류를 남기며, 재시도 종료 후에는 전달이 보장되지 않습니다.

대기열에는 1,000건의 전송 내역이 저장됩니다. 대기열이 가득 차면 저널 이벤트 스캔이 일시 중지되며, 공간이 확보되면 다시 재개됩니다. 대기열에 추가할 수 없는 전체 내보내기 작업이 완료되면 가시적인 대기열 오류가 발생합니다. 알림 처리 시마다 최대 5건의 전송 시도가 이루어지며, 최근 100건의 시도 기록이 보관됩니다. 수신처를 제거하면 해당 수신처의 대기 중인 전송 내역도 함께 제거됩니다.

n8n 예시#

예제 워크플로를 가져오세요. 이 워크플로는 비활성 상태이며 기밀 정보나 하위 작업이 포함되어 있지 않습니다. n8n 워커 환경에서 TGWITNESS_WEBHOOK_SECRET를 설정하고, 해당 환경에 대한 액세스를 허용하며, Code 노드에 대해 crypto 내장 기능을 허용하십시오. 이 예제는 Webhook 노드의 raw-body 옵션을 사용하고, 서명/신선도를 확인하며, 검증된 이벤트를 확인합니다. 이는 노드의 문서화된 구현 방식과 일치합니다.

SIEM 기록이나 알림을 추가하기 전에, event_id를 키로 사용하는 내구성 있는 이멱포텐트 저장소를 추가하십시오. 전송하기로 선택한 데이터에 따라 n8n 워크플로우 편집 및 실행 로그 보존 기간을 제한하십시오. TgWitness는 인바운드 명령을 추가하지 않습니다.