Echobell
App Store Google Play

Webhook 연동 - HTTP 트리거 완벽 가이드

Echobell Webhook 연동하기: HTTP 메서드, 변수, 템플릿, 헤더, 그리고 즉시 알림을 받기 위한 실전 예시를 안내합니다.

Webhook은 Echobell 알림을 트리거하는 가장 다재다능한 방법입니다. 이 종합 가이드에서는 기본 개념부터 고급 활용 패턴까지, Webhook 기반 알림을 시스템에 연동하기 위해 알아야 할 모든 내용을 다룹니다.

Webhook이란

Webhook은 한 애플리케이션이 HTTP 콜백을 통해 다른 애플리케이션에 실시간 정보를 전달하는 방식입니다. 누군가에게 알려 주는 전화번호라고 생각하면 됩니다. 상대가 그 번호로 전화를 걸면 내 전화기가 울립니다. 디지털 세계에서도 마찬가지로, 한 시스템에서 어떤 일이 일어나면(CPU 사용률 급등, 빌드 실패, 신규 주문 등) 사용자가 미리 알려 준 URL(Webhook)로 HTTP 요청이 전송되고, 이를 통해 시스템에서 특정 동작이 실행됩니다.

예를 들어 서버의 CPU 사용률이 지나치게 높아지면 모니터링 시스템이 Echobell의 Webhook URL을 호출하고, 그러면 알림이 트리거되어 상황을 알려 줍니다. 이 과정은 자동으로, 실시간으로 이루어지므로 CPU 사용률을 직접 계속 확인할 필요가 없습니다.

Webhook은 이벤트 기반 아키텍처의 근간이며, 사실상 모든 최신 클라우드 서비스, 모니터링 도구, SaaS 플랫폼이 지원합니다. 가볍고 빠르며, 사용자 쪽에 특별한 인프라도 필요하지 않습니다. HTTP 클라이언트만 있으면 됩니다.

Webhook의 장점

  • 실시간: 이벤트가 발생하면 보통 1~2초 안에 알림이 즉시 트리거됩니다
  • 범용성: 거의 모든 최신 서비스와 프로그래밍 언어에서 지원합니다
  • 유연성: 사용자 지정 데이터를 전달해 풍부하고 맥락 있는 알림을 만들 수 있습니다
  • 안정성: HTTP 기반이므로 표준 상태 코드와 오류 처리 방식을 그대로 활용합니다
  • 확장성: 폴링이 필요 없으며, 이벤트가 발생할 때만 알림이 전송됩니다

개요

Echobell 채널마다 고유한 Webhook URL을 설정할 수 있습니다. 이 URL이 호출되면 채널은 설정된 알림 템플릿과 전달된 변수를 바탕으로 모든 구독자에게 알림을 보냅니다.

Webhook URL 형식

https://hook.echobell.one/t/{channel-token}

채널의 Webhook URL은 Echobell 앱의 채널 상세 화면에서 확인할 수 있습니다.

Webhook 요청 보내기

Echobell Webhook은 GET과 POST 메서드를 모두 지원합니다.

GET 요청

쿼리 파라미터로 변수를 전달할 수 있습니다.

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

POST 요청

POST 요청에서는 JSON 본문에 변수를 담아 보냅니다.

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

POST 전용

각 채널에는 Echobell 앱의 고급 설정에 POST 전용 스위치가 있습니다. 기본값은 꺼짐입니다.

이 옵션을 켜면 POST만 채널을 트리거할 수 있습니다. Webhook URL로 보낸 GET 요청은 405 Method Not Allowed로 거부되며 알림도 전송되지 않습니다.

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

HEAD 요청은 영향을 받지 않습니다 — POST 전용이 켜져 있든 꺼져 있든 항상 200으로 응답하며 알림을 트리거하지 않습니다.

채팅 메시지, 위키 페이지, 브라우저 주소창처럼 링크를 자동으로 불러오는 곳에 Webhook URL이 놓이게 된다면 이 옵션을 켜세요. 그러면 URL을 미리 보거나 열더라도 알림이 발송되지 않습니다. 호출하는 쪽 가운데 하나라도 GET으로 채널을 트리거한다면 이 옵션은 꺼 두십시오.

특수 변수

Echobell은 알림에 기능을 더해 주는 특수 변수를 지원합니다.

  • externalLink: 요청에 포함하면 알림 기록 화면에 클릭할 수 있는 링크가 만들어집니다. 상세 정보나 관련 리소스로 연결할 때 유용합니다.

외부 링크를 사용하는 예시입니다.

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

템플릿 변수

Webhook으로 전달한 변수는 {{variableName}} 문법을 사용해 알림 템플릿에서 활용할 수 있습니다.

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

채널이 트리거되면 이 템플릿에는 Webhook 요청으로 전달한 값이 채워집니다.

시스템 시간 변수(UTC)

직접 전송하는 데이터 외에도 Echobell은 템플릿과 조건에서 항상 사용할 수 있는 읽기 전용 시스템 시간 변수를 제공합니다. 모든 값은 UTC 기준으로 계산됩니다. 플랫 필드로는 date, time, year, month, dayOfWeek, hour, minute, second가 있습니다. sys.dayOfWeekName, sys.epochMs, sys.epochSeconds 등 나머지 값은 sys. 네임스페이스에서만 사용할 수 있습니다. 전체 목록과 예시는 조건 문서를 참고하세요.

일반적인 사용 사례

Webhook은 Echobell에서 가장 널리 쓰이는 트리거 방식이며, 특히 다음과 같은 용도에 유용합니다.

DevOps 및 모니터링

  • 서버 모니터링: Prometheus나 Grafana 같은 모니터링 시스템에서 보내는 CPU, 메모리, 디스크 사용량 알림
  • 가동 시간 모니터링: Uptime Kuma나 UptimeRobot에서 보내는 웹사이트 및 서비스 가용성 알림
  • 컨테이너 모니터링: Docker, Kubernetes 파드 장애, 리소스 부족
  • 로그 집계: 로그 관리 시스템에서 발생한 심각한 오류와 예외

개발 및 CI/CD

  • 빌드 알림: GitHub Actions나 GitLab CI에서 보내는 빌드 실패, 테스트 결과, 배포 상태
  • 코드 품질: 린트 오류, 보안 취약점, 코드 커버리지 변화
  • 저장소 이벤트: 풀 리퀘스트, 커밋, 릴리스, 협업자 활동
  • 배포 추적: 배포 성공, 롤백, 환경 변경

비즈니스 애플리케이션

  • 이커머스: 신규 주문, 결제 확인, 재고 경고, 배송 상태 업데이트
  • CRM: 신규 리드, 거래 성사, 지원 티켓, 고객 응대 내역
  • 결제 처리: 거래 완료, 환불 요청, 이상 거래 알림
  • 양식 제출: 문의 양식, 설문 응답, 가입 완료

IoT 및 스마트 홈

  • 스마트 홈 이벤트: Home Assistant를 통한 문 센서, 동작 감지, 온도 변화
  • IoT 기기: 센서 측정값, 기기 상태 변화, 연결 문제
  • 보안 시스템: 경보 발생, 카메라 동작 감지, 출입 통제 이벤트
  • 환경 모니터링: 온도, 습도, 공기질 임계값 초과

트레이딩 및 금융

  • 시장 알림: TradingView에서 보내는 가격 변동, 기술적 지표
  • 포트폴리오 모니터링: 포지션 변경, 마진 콜, 계좌 잔고
  • 경제 이벤트: 뉴스 발표, 실적 보고, 시장 심리 변화

주요 플랫폼별 구체적인 설정 방법은 연동 가이드를 참고하세요.

모범 사례

오류 처리

HTTP 상태 코드만 보고 판단하지 마시고, 항상 JSON 응답 본문을 열어 success 필드를 확인하세요.

  • 200 OK: 요청이 접수되었습니다. JSON 본문을 확인하세요. success: true는 채널이 트리거되었다는 뜻이고, success: false는 요청은 받아들여졌지만 알림은 전송되지 않았다는 뜻입니다(예를 들어 존재하지 않는 채널 토큰도 HTTP 200을 반환합니다).
  • 400 Bad Request: 채널 토큰의 길이가 올바르지 않습니다. Webhook URL을 수정하세요.
  • 405 Method Not Allowed: 채널에 POST 전용이 켜져 있는데 요청이 POST가 아니었습니다. 호출하는 쪽을 POST로 바꾸거나 설정을 끄세요.
  • 500 Server Error: 일시적인 문제이므로 지수 백오프로 재시도하세요

Echobell은 Webhook 호출에 속도 제한을 두지 않으므로 429 응답은 발생하지 않습니다. 길이는 올바르지만 존재하지 않는 토큰도 200과 함께 success: false를 반환하므로, HTTP 상태 코드가 아니라 JSON의 success 필드를 기준으로 분기하세요.

속도 제한

알림 시스템에 과부하가 걸리지 않도록 Webhook 호출 사이에 적절한 간격을 두세요.

  • 지속적인 모니터링에서는 여러 이벤트를 하나의 알림으로 묶어 보내세요
  • 조건을 사용해 중요하지 않은 이벤트를 걸러 내세요
  • 짧은 시간에 몰리는 이벤트(예: 단시간에 발생한 다수의 오류)는 집계하는 방안을 고려하세요
  • 중요한 알림의 신뢰성을 지키려면 같은 트리거를 연달아 반복 전송하지 마세요

데이터 보안

Webhook URL은 신뢰할 수 있는 시스템과 서비스에만 공유하세요.

  • Webhook URL은 비밀 값으로 취급하세요. 알림을 보낼 수 있는 직접적인 권한이기 때문입니다
  • Webhook URL을 공개 저장소에 커밋하거나 공개 문서에 공유하지 마세요
  • Webhook URL은 주기적으로, 그리고 팀원이 이탈할 때 교체하세요
  • URL이 유출되었다면 채널의 "토큰 재설정" 기능으로 기존 URL을 무효화하세요
  • URL은 환경 변수나 시크릿 관리 시스템에 저장하는 방안을 고려하세요

변수 이름 짓기

Webhook 호출에서는 명확하고 일관된 변수 이름을 사용하세요.

  • 의미가 드러나는 이름을 쓰세요. s나 srv 대신 server_name처럼 씁니다
  • 채널 전반에 걸쳐 일관된 명명 규칙을 따르세요
  • 템플릿이 어떤 변수를 필요로 하는지 문서로 남기세요
  • 전송하기 전에 필요한 변수가 모두 있는지 검증하세요

테스트

프로덕션에 적용하기 전에 Webhook 연동을 충분히 테스트하세요.

  1. 처음 테스트할 때는 curl, Postman 또는 사용하는 언어의 HTTP 클라이언트를 활용하세요
  2. 간단한 템플릿부터 시작해 점차 복잡도를 높이세요
  3. GET과 POST를 모두 테스트해 어느 쪽이 가장 잘 맞는지 확인하세요
  4. 특수 문자와 유니코드가 올바르게 처리되는지 확인하세요
  5. 오류 상황(변수 누락, 잘못된 JSON)을 테스트해 동작 방식을 파악하세요
  6. 개발 중에는 프로덕션 채널과 분리된 테스트 채널을 사용하세요

템플릿 설계

선택적 변수가 없더라도 쓸모 있는 템플릿이 되도록 설계하세요.

  • 선택적 데이터에는 기본값이나 대체 값을 마련하세요
  • 변수가 없어도 자연스럽게 처리되도록 템플릿을 구성하세요
  • 변수가 있는 경우와 없는 경우를 다양하게 조합해 템플릿을 테스트하세요
  • 선택적인 부분에는 조건식을 사용하세요

모니터링

Webhook 연동이 제대로 동작하는지 모니터링하세요.

  • 애플리케이션에서 성공한 Webhook 호출과 실패한 호출을 모두 기록하세요
  • 알림 전달률과 응답 시간을 추적하세요
  • Webhook 오류나 이상 패턴에 대한 알림을 설정하세요
  • 중요한 Webhook 연동은 주기적으로 점검하고 테스트하세요

개인정보 보호 및 보안

Echobell이 Webhook 데이터를 어떻게 처리하는지 알아보세요.

저장되는 정보

  • Echobell 서버:

    • Webhook URL(토큰) - 들어온 요청을 채널로 전달하는 데 필요합니다
    • 채널 설정 - 템플릿, 조건, 각종 설정
    • 구독 관계 - 어떤 사용자가 어떤 채널을 구독하는지

  • 사용자 기기:

    • 알림 내용 - 렌더링된 제목과 본문 텍스트
    • 트리거 기록 - 알림을 받은 시각
    • 변수 값 - Webhook 호출로 전달된 데이터
    • 링크 및 메타데이터 - externalLink를 비롯한 관련 데이터

저장되지 않는 정보

  • 원본 Webhook 페이로드는 영구적으로 저장하지 않습니다
  • 요청에 담긴 민감한 데이터를 기록하거나 보관하지 않습니다
  • 어떤 목적으로도 알림 내용을 분석하거나 가공하지 않습니다
  • Webhook 데이터를 제3자와 공유하지 않습니다

보안 권장 사항

  • Webhook URL을 API 키처럼 취급하세요 - 별도의 인증 없이 알림을 보낼 수 있는 수단입니다
  • URL을 주기적으로 교체하세요 - "토큰 재설정" 기능으로 새 URL을 만들 수 있습니다
  • HTTPS 클라이언트를 사용하세요 - Echobell은 HTTPS 연결만 허용하지만, 클라이언트가 인증서를 검증하는지도 확인하세요
  • Webhook 호출 출처를 검증하세요 - 가능하다면 Webhook을 호출할 수 있는 IP나 서비스를 제한하세요
  • 오남용을 감시하세요 - 이상 패턴이나 허가되지 않은 사용이 없는지 살펴보세요
  • 환경을 분리하세요 - 개발, 스테이징, 프로덕션에 서로 다른 채널을 사용하세요

자세한 내용은 지원 문서에서 확인하세요.

문제 해결

Webhook이 예상대로 동작하지 않는다면 다음 진단 절차를 따라 보세요.

Webhook이 알림을 트리거하지 않는 경우

  1. Webhook URL이 올바른지 확인하세요

    • Echobell 앱에서 URL을 그대로 복사하세요
    • 불필요한 공백이나 문자가 섞이지 않았는지 확인하세요
    • 다른 도메인이 아니라 https://hook.echobell.one/t/를 사용하고 있는지 확인하세요

  2. 채널이 활성 상태인지 확인하세요

    • Echobell 앱에서 해당 채널을 여세요
    • 채널이 삭제되거나 보관되지 않았는지 확인하세요
    • Webhook 토큰을 재설정하지 않았는지 확인하세요(재설정하면 기존 URL이 무효화됩니다)

  3. JSON 페이로드 형식이 올바른지 확인하세요(POST 요청의 경우)

    • JSON 검증 도구로 페이로드를 점검하세요
    • 문자열에 따옴표가 제대로 붙어 있는지 확인하세요
    • Content-Type 헤더가 application/json으로 설정되어 있는지 확인하세요

  4. 템플릿에 필요한 변수가 모두 전달되고 있는지 확인하세요

    • 알림 템플릿에서 어떤 변수를 사용하는지 확인하세요
    • 해당 변수가 Webhook 요청(쿼리 파라미터 또는 JSON 본문)에 들어 있는지 확인하세요
    • 누락된 변수는 빈 문자열로 렌더링된다는 점을 기억하세요

  5. 채널에 활성 구독자가 있는지 확인하세요

    • 알림은 채널을 구독한 사람이 있을 때만 전송됩니다
    • 앱의 채널 목록에서 구독 상태를 확인하세요
    • 구독이 실수로 해제되지 않았는지 확인하세요

알림이 잘못 렌더링되는 경우

  1. 변수 이름이 일치하지 않습니다

    • 템플릿은 {{server_name}}을 쓰는데 Webhook은 serverName을 보내는 경우입니다
    • 변수 이름은 대소문자를 구분하며 정확히 일치해야 합니다
    • 변수 이름에 오타가 없는지 확인하세요

  2. 중첩된 데이터에 접근할 수 없습니다

    • 점 표기법 {{user.name}} 또는 대괄호 표기법 {{user["name"]}}을 사용하세요
    • JSON 구조가 템플릿에서 기대하는 형태와 맞는지 확인하세요
    • 먼저 단순한 플랫 변수로 테스트한 뒤 중첩 구조를 추가하세요

  3. 특수 문자 때문에 문제가 생깁니다

    • 쿼리 파라미터를 올바르게 URL 인코딩하세요
    • POST 본문에서는 JSON 특수 문자를 이스케이프하세요
    • 먼저 단순한 ASCII 텍스트로 테스트하세요

연동 테스트하기

curl로 Webhook을 직접 테스트해 보세요.

# Test with query parameters
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Test with JSON body
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

모든 설정이 올바르다면 즉시 알림이 도착합니다.

그래도 문제가 해결되지 않는다면

위 단계를 모두 시도했는데도 문제가 계속된다면 다음을 참고하세요.

  • 지원 센터에서 더 많은 문제 해결 가이드를 확인하세요
  • 알려진 문제나 서비스 상태 업데이트가 있는지 확인하세요
  • 다음 정보와 함께 echobell@weelone.com으로 문의해 주세요
    • 문제 설명
    • 이미 시도해 본 방법
    • 예시 Webhook URL(토큰은 지우거나 가린 상태로)
    • 요청 페이로드 샘플
    • 예상 동작과 실제 동작

다음 단계

이제 Webhook 연동을 이해하셨으니 다음 내용도 살펴보세요.

Echobell을 시스템에 연동할 준비가 되셨나요? 첫 채널을 만들고 즉시 알림을 받아 보세요!