Webhook 연동 가이드

Webhook을 설정하면 Miharu의 모니터링 결과(시스템 감지 이벤트)를 지정한 URL로 JSON 형식으로 POST 전송합니다. Zapier / Make / n8n / 자체 서버 등과 연동해 알림을 자유롭게 처리할 수 있습니다.

이 기능은 개발자·파워 유저를 위한 기능입니다. 수신 측 구현이 필요합니다.

1. 설정 방법

1. 1앱에서 “외부 알림” → “Webhook”을 엽니다
2. 2전송할 Webhook URL을 입력합니다(https://로 시작하는 URL이어야 합니다)
3. 3필요에 따라 “알림 내용” 필터(특정 모니터링 그룹만 등)를 설정합니다
4. 4저장하면 설정 완료를 알리는 테스트 알림이 1건 전송됩니다

2. HTTP 전송 사양

서명(HMAC 등) 헤더는 부여되지 않습니다. Webhook URL 자체가 비밀 정보입니다(아래 보안 참조).

3. 페이로드(공통 필드)

4. 이벤트 종류와 detail

page_changed의 diff

diff는 변경된 부분의 배열입니다. 각 요소는 다음 중 하나입니다:

• { "op": "added", "text": "..." }… 추가된 줄
• { "op": "removed", "text": "..." }… 삭제된 줄
• { "op": "replaced", "before": "...", "after": "..." }… 대체된 줄

truncated가 true인 경우, 차이가 커서 일부가 생략되었습니다.

5. 샘플

{
  "source": "miharu",
  "version": "1",
  "id": "5c2e1b7a-9f3d-5a6b-8c4e-1d2f3a4b5c6d",
  "timestamp": "2026-05-22T01:23:45Z",
  "language": "ko",
  "event": "page_changed",
  "monitor": { "id": "abc123", "name": "상품 페이지", "url": "https://example.com/item" },
  "message": { "body": "페이지가 업데이트되었습니다.", "label": "업데이트" },
  "detail": {
    "diff": [
      { "op": "replaced", "before": "품절", "after": "재고 있음" },
      { "op": "added", "text": "오늘 입고되었습니다" }
    ],
    "truncated": false
  }
}

{
  "source": "miharu", "version": "1", "id": "…",
  "timestamp": "2026-05-22T01:23:45Z", "language": "ko",
  "event": "keyword_hit",
  "monitor": { "id": "abc123", "name": "재고 페이지", "url": "https://example.com/stock" },
  "message": { "body": "키워드를 감지했습니다.", "label": "키워드" },
  "detail": { "hits": [ { "keywords": ["입고"], "excerpts": ["…오늘 입고되었습니다…"] } ] }
}

{
  "…": "…",
  "event": "new_link",
  "message": { "body": "새 링크를 감지했습니다.", "label": "새 링크" },
  "detail": { "links": [ { "text": "신제품 안내", "url": "https://example.com/news/123" } ] }
}

{
  "…": "…",
  "event": "price_changed",
  "message": { "body": "“가격”이(가) 변동되었습니다.\n\n1980 → 1480", "label": "가격·값" },
  "detail": { "target_name": "가격", "before": "1980", "after": "1480" }
}

6. 중복 제거(멱등성)

동일한 이벤트는 재전송(리트라이) 시에도 항상 같은 id로 도착합니다(X-Miharu-Notification-Id 헤더에도 같은 값이 들어갑니다). 수신 측에서는 id를 사용해 중복 처리를 방지해 주세요.

7. 보안

• HTTPS 필수(https:// URL만 설정할 수 있습니다).
• 서명 헤더가 없으므로 Webhook URL 자체를 비밀 정보로 다뤄 주세요(유출되면 제3자가 가짜 알림을 보낼 수 있습니다).
• 필요에 따라 URL에 무작위 토큰(예: https://example.com/hook/<무작위 문자열>)을 포함하고 수신 측에서 검증해 주세요.
• 전송 원본의 간이 판별에는 User-Agent: Miharu-Webhook/1.0이나 X-Miharu-* 헤더를 이용할 수 있습니다(어디까지나 보조 수단입니다).

8. 연동 서비스

각 서비스에서 “수신용 URL”을 발급하고, 그것을 Miharu의 Webhook URL로 설정하기만 하면 됩니다.

• Zapier: 트리거 “Webhooks by Zapier” → “Catch Hook”의 URL
• Make: “Custom webhook”의 URL
• n8n: “Webhook” 노드의 URL
• 자체 서버: JSON 본문을 받아 2xx를 반환하는 엔드포인트

9. 제한·주의

• Webhook으로 도착하는 것은 시스템 감지 이벤트(각종 감지)와 시스템 알림입니다.
• 차이나 텍스트는 길 경우 생략될 수 있습니다(truncated: true 등).
• “알림 내용” 필터 설정으로 전송 대상을 특정 모니터링 그룹으로 좁힐 수 있습니다.

10. 잘 도착하지 않을 때

• URL이 https://로 시작하는지 확인해 주세요.
• 수신 측이 2xx를 반환하는지 확인해 주세요(리디렉션이나 오류는 실패로 처리됩니다).
• 2xx 이외가 연속되어 전송이 중지되지 않았는지 확인해 주세요(앱에서 상태를 확인하고 다시 설정하면 재개됩니다).
• 처리에 10초 이상 걸리지 않는지 확인해 주세요(타임아웃). 수신은 즉시 2xx, 처리는 비동기로 해 주세요.

의견이나 요청은 앱의 “의견 및 개선 제안”에서 보내 주세요.