웹훅 사용 가이드
시작하기
코인검색기 웹훅을 사용하기 위한 첫 단계를 시작해 보세요. 몇 분 안에 설정을 완료하고 실시간 데이터를 받아볼 수 있습니다.
Webhook 설정 방법
1
알림 설정 이동: 코인검색기 서비스 내 ‘알림 설정’ 페이지로 이동합니다.
2
옵션 활성화: Webhook 사용 옵션을 활성화합니다.
3
URL 입력: 수신 받을 웹훅 URL을 입력합니다. (예:
https://…)4
메시지 입력 (선택): 함께 전송할 커스텀 메시지가 있다면 입력합니다.
Request 규격
MethodPOST
Content-Typeapplication/json
User-AgentCoinSearch-Webhook/1.0
Payload (JSON) 상세
웹훅 요청의 본문(Body)은 다음과 같은 JSON 구조를 가집니다.
| 필드명 | 타입 | 설명 |
|---|---|---|
id | string | 웹훅 메시지의 고유 식별자(UUID). 중복 수신 방지 및 추적 용도로 사용 가능 |
title | string | 조건을 만족한 검색식의 제목 (예: “볼린저밴드 하단 터치 급등 포착”) |
exchange | string | 검색 대상 거래소 (예: “binance”, “upbit”, “bithumb”, “okx”, “bitget”, “bybit”) |
market | string | 시장 구분 (“spot”: 현물, “futures”: 선물) |
quote | string | 기준 마켓 (거래 통화쌍의 기준 단위) (예: “USDT”, “KRW”) |
symbols | array | 조건에 포착된 코인 심볼 리스트 (예: [“BTC”, “ETH”, “SOL”]) |
message | string | 선택 사용자가 설정한 커스텀 메시지 값이 없을 경우 문자열 “null” 형태로 담겨 전달됩니다. |
timestamp | number | 웹훅 전송 시각 (Unix Timestamp ms 형식) |
페이로드 예시
webhook-payload.json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "볼린저밴드 하단 터치 급등 포착",
"exchange": "binance",
"market": "spot",
"quote": "USDT",
"symbols": ["BTC", "ETH", "SOL"],
"message": "자동매매 봇 실행 바람",
"timestamp": 1701234567890
}Response 규격 (수신 서버 권장 사항)
✅
올바른 응답 처리 방법
- HTTP Status Code: 수신 성공 시 반드시
200 OK반환 - 응답 제한 시간: 웹훅 발송 후 3초 이내에 상태 코드 200 응답이 오지 않으면 수신 실패로 간주됩니다. 실제 서비스 처리(DB 저장 등)가 오래 걸린다면, 200 응답만 즉시 반환하고 실제 로직은 별도로 비동기 처리하는 것을 권장합니다.
- 실패 시 재시도 없음: 서버 타임아웃이나 서버 측 에러(4xx, 5xx)가 발생하더라도 웹훅 요청은 무한 루프를 막기 위해 재발송되지 않습니다.
수신 테스트 해보기 (Mock Request)
실제 조건식에 코인이 포착될 때까지 기다릴 필요 없이, 터미널에서 아래의 curl 명령어를 복사하여 방금 개발하신 여러분의 로컬/개발 서버 웹훅 엔드포인트로 수신 테스트를 진행해 보세요.
(본인의 서버 주소로 URL을 변경하여 실행하시기 바랍니다)
🍎 Mac / Linux (curl)
Terminal (bash/zsh)
curl -X POST "http://localhost:3000/webhook?token=YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-H "User-Agent: CoinSearch-Webhook/1.0" \
-d '{
"id": "test-mock-uuid-0001",
"title": "[테스트] 볼린저밴드 급등",
"exchange": "binance",
"market": "spot",
"quote": "USDT",
"symbols": ["BTC"],
"message": "이것은 가짜 모의 웹훅 테스트입니다.",
"timestamp": 1701234567890
}'🪟 Windows (PowerShell)
＞
Windows PowerShellInvoke-RestMethod -Uri "http://localhost:3000/webhook?token=YOUR_SECRET_TOKEN" `
-Method POST `
-Headers @{
"Content-Type" = "application/json"
"User-Agent" = "CoinSearch-Webhook/1.0"
} `
-Body '{
"id": "test-mock-uuid-0001",
"title": "[테스트] 볼린저밴드 급등",
"exchange": "binance",
"market": "spot",
"quote": "USDT",
"symbols": ["BTC"],
"message": "이것은 가짜 모의 웹훅 테스트입니다.",
"timestamp": 1701234567890
}'