Webhook 連携ガイド

Webhookを設定すると、見ハルの監視結果（システムアラート）を、あなたが指定した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": "ja",
  "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": "ja",
  "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自体を秘密情報として扱ってください（漏洩すると第三者が偽の通知を送れます）。
• 必要に応じて、URLにランダムなトークン（例：https://example.com/hook/<ランダム文字列>）を含め、受信側で検証してください。
• 送信元の簡易判別には User-Agent: Miharu-Webhook/1.0 や X-Miharu-* ヘッダを利用できます（あくまで補助）。

8. 連携サービス

各サービスで「受信用URL」を発行し、それを見ハルの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、処理は非同期に。

お気づきの点やご要望は、アプリの「ご意見・改善のご要望」からお送りください。