Echobell
App Store Google Play

다이렉트 알림 - 즉시 알림을 위한 개인 API 키

개인 API 키로 알림을 바로 보내세요. 채널 설정은 필요 없습니다. 다이렉트 키를 만들고 제목, 본문, 링크가 포함된 즉시 알림을 트리거하는 방법을 알아보세요.

다이렉트 알림을 사용하면 간단한 Webhook URL 하나로 개인 알림을 보낼 수 있습니다 — 채널 설정도, 템플릿도, 구독자도 필요 없습니다. 키를 만들고 URL을 호출하기만 하면 기기로 즉시 알림이 도착합니다.

다이렉트란?

채널은 다른 사람과 공유할 수 있는 구조화된 템플릿 기반 알림에 잘 어울립니다. 하지만 빌드 완료, 스크립트 종료, 센서 작동처럼 간단한 개인 알림 하나만 필요할 때도 있습니다. 다이렉트는 바로 이런 용도로 설계되었습니다.

다이렉트를 사용하면 고유한 Webhook URL과 연결된 개인 API 키를 받게 됩니다. 제목과 본문을 담아 이 URL을 호출하면 알림이 사용자에게 곧바로 전송됩니다. 채널 설정은 필요하지 않습니다.

다이렉트와 채널 중 무엇을 선택할까요

다이렉트채널
설정키를 만들고 URL 사용채널을 만들고 템플릿 구성
대상본인만구독한 모든 사람
템플릿없음 — 요청마다 제목과 본문을 직접 지정변수를 사용하는 구성 가능한 템플릿
조건없음조건부 전송 지원
적합한 용도개인 스크립트, 간단한 알림, 자동화공유 알림, 구조화된 워크플로

시작하기

1. 다이렉트 키 만들기

Echobell 앱에서 채널 목록 상단의 다이렉트를 탭하세요. 이어서 생성을 탭하면 새 다이렉트 키가 만들어집니다. 알아보기 쉬운 이름을 지정하세요(예: "빌드 서버", "홈 랩", "트레이딩 봇").

2. Webhook URL 복사하기

각 다이렉트 키에는 다음 형식의 고유한 Webhook URL이 있습니다.

https://hook.echobell.one/d/{your-key-token}

앱의 다이렉트 키 상세 화면에서 이 URL을 확인하고 복사할 수 있습니다. 토큰은 보안을 위해 기본적으로 가려져 있으며, 탭하면 표시됩니다.

3. 알림 보내기

title과 body가 담긴 JSON 본문으로 Webhook URL을 호출하세요.

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}

이것으로 끝입니다 — 알림이 즉시 도착합니다.

요청 보내기

POST 요청(권장)

알림 내용을 담은 JSON 본문을 보내세요.

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}

GET 요청

쿼리 문자열로 파라미터를 전달할 수도 있습니다.

GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25

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으로 응답하며 알림을 트리거하지 않습니다.

이 설정은 키마다 따로 적용되므로, 셸 한 줄 명령용으로는 GET을 허용하는 키를 두고 채팅이나 위키 페이지에 붙여 넣는 URL에는 POST 전용 키를 사용할 수 있습니다.

요청 필드

모든 필드 이름은 대소문자를 구분하지 않습니다 — JSON 본문으로 전달하든 쿼리 문자열로 전달하든 title, Title, TITLE은 모두 같게 처리됩니다.

필드타입필수설명
titlestring아니요알림 제목. 생략하면 "Direct Notification"이 사용됩니다.
bodystring아니요알림 본문 텍스트.
externalLinkstring아니요알림 기록에 표시되는 클릭 가능한 링크.
notificationTypestring아니요알림 긴급도 수준. active, time-sensitive, calling 중 하나를 사용합니다. 기본값은 active입니다. 알림 유형을 참고하세요.

알림 유형

notificationType 필드로 다이렉트 알림의 긴급도 수준을 지정할 수 있습니다.

유형설명
active일반 알림으로, 평소처럼 전달됩니다. 기본값입니다.
time-sensitive집중 모드를 뚫고 전달될 수 있는 높은 우선순위의 알림입니다.
calling긴급한 상황을 위한 전화 형태의 알림입니다. 활성화된 Premium 구독이 필요합니다. Premium이 없으면 time-sensitive로 대체됩니다.

알림 유형을 지정한 예시입니다.

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}

응답 형식

요청이 성공하면 다음과 같이 응답합니다.

{
  "success": true,
  "message": "Notification triggered successfully."
}

키가 유효하지 않거나 존재하지 않는 경우입니다(이때도 HTTP 200을 반환한다는 점에 유의하세요).

{
  "success": false,
  "message": "Direct key not found."
}

다이렉트 키 관리

여러 개의 키

용도별로 다이렉트 키를 여러 개 만들 수 있습니다.

  • "CI 서버" — 빌드 및 배포 알림용
  • "홈 자동화" — IoT 센서 알림용
  • "크론 작업" — 예약 작업 결과 알림용
  • "트레이딩 봇" — 시장 알림용

각 키에는 서로 독립적인 Webhook URL이 있습니다. 알림 기록은 이를 트리거한 키와 자동으로 연결되므로, 어떤 서비스가 보낸 알림인지 쉽게 확인할 수 있습니다.

토큰 재설정

키의 Webhook URL이 유출되었다면 키 상세 화면에서 토큰을 재설정할 수 있습니다. 그러면 새 URL이 만들어지고 기존 URL은 즉시 무효화됩니다. 기존 URL을 사용하던 스크립트나 서비스는 모두 업데이트하세요.

키 삭제

다이렉트 키를 삭제하면 해당 Webhook URL이 영구적으로 무효화됩니다. 기존 URL로 보낸 요청은 모두 실패합니다.

일반적인 활용 사례

셸 스크립트

# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'

크론 작업

# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'

Python

import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)

Node.js

await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});

GitHub Actions

- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'

모범 사례

보안

  • 다이렉트 키 URL은 비밀 정보로 취급하세요 — URL을 아는 사람은 누구나 알림을 보낼 수 있습니다
  • 환경 변수를 사용하세요 — 스크립트와 CI/CD에 키 토큰을 저장할 때 활용합니다
  • 토큰을 재설정하세요 — 키가 유출되었다고 의심되면 즉시 재설정합니다
  • 서비스마다 키를 따로 만드세요 — 필요할 때 개별적으로 폐기할 수 있습니다

체계적인 관리

  • 키 이름을 알아보기 쉽게 지으세요 — 키가 여러 개일 때 관리가 훨씬 수월해집니다
  • 서비스당 키를 하나씩 사용하세요 — 알림 출처를 파악하고 접근 권한을 폐기하기 쉬워집니다
  • 사용하지 않는 키는 삭제하세요 — 공격 표면을 줄일 수 있습니다

오류 처리

다이렉트를 스크립트에 연동할 때는 HTTP 상태 코드가 아니라 JSON의 success 필드를 기준으로 분기하세요.

  • 200 OK: 요청이 접수되었습니다. JSON 본문을 확인하세요. success: true는 알림이 트리거되었다는 뜻이고, success: false는 트리거되지 않았다는 뜻입니다. 알 수 없거나 재설정된 다이렉트 키는 HTTP 200과 함께 { "success": false, "message": "Direct key not found." }를 반환하며, 404가 아닙니다.
  • 400 Bad Request: 키 토큰의 길이가 올바르지 않습니다. URL을 수정하세요.
  • 405 Method Not Allowed: 해당 키에 POST 전용이 켜져 있는데 요청이 POST가 아니었습니다. 호출하는 쪽을 POST로 바꾸거나 설정을 끄세요.

Echobell은 다이렉트 호출에 속도 제한을 두지 않으므로 429 응답은 발생하지 않습니다.

개인정보 보호와 보안

저장되는 정보

  • 당사 서버:

    • 다이렉트 키 메타데이터(이름, 해시된 토큰, 소유자)
    • 요청 페이로드는 전달을 위해 일시적으로 처리 및 저장됩니다

  • 사용자 기기:

    • 알림 내용(제목, 본문)
    • 트리거 기록과 타임스탬프
    • 외부 링크

저장되지 않는 정보

  • 전달이 끝난 요청 페이로드는 영구적으로 보관하지 않습니다
  • 알림 내용을 분석하지 않습니다
  • 사용자의 데이터를 제3자와 공유하지 않습니다

문제 해결

알림이 오지 않는 경우

  1. Webhook URL을 확인하세요 — 앱에서 직접 복사하고, 공백이 섞이지 않았는지 확인합니다
  2. 키가 아직 있는지 확인하세요 — 삭제되었거나 토큰이 재설정되었을 수 있습니다
  3. 알림 권한을 확인하세요 — Echobell 앱에는 기기의 알림 권한이 필요합니다
  4. curl로 테스트하세요 — HTTP 클라이언트 문제인지 확인합니다. 
    curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "body": "Hello from Direct"}'

요청 오류

  • JSON 구문 분석 오류: Content-Type: application/json 헤더가 설정되어 있고 본문이 올바른 JSON인지 확인하세요
  • 키를 찾을 수 없음: "Direct key not found." 메시지와 함께 "success": false가 반환되면 토큰이 재설정되었거나 키가 삭제된 것입니다(HTTP 상태는 여전히 200입니다)

문제가 계속되나요?

  • 지원 센터에서 더 많은 도움말을 확인하세요
  • echobell@weelone.com으로 다음 내용을 담아 문의해 주세요
    • 문제에 대한 설명
    • 예시 요청(토큰은 가린 상태로)
    • 예상 동작과 실제 동작

다음 단계