セルフホスト環境からiPhoneへ確実にプッシュ通知を届ける方法

Grafana のアラートが深夜 3 時に発火する。サーバーのログには Webhook の呼び出しが成功したと記録されている。それなのに iPhone は何も鳴らない。セルフホストの監視は障害の検知は得意です。しかし、そのメッセージをスマホに届けるところで、多くのホームラボ環境が機能しなくなります。
このガイドでは、セルフホスト環境から iPhone へプッシュ通知を送るのがなぜ難しいのか、確実に届く経路はどのようなものか、そして Grafana、Uptime Kuma、n8n、cron ジョブ、シェルスクリプトをどう接続するかを説明します。最初の通知が届くまでにかかる時間は約 5 分です。
セルフホスト環境で iOS へのプッシュ通知が失敗する理由
iPhone に届けられるのは APNs だけ
iPhone へのプッシュ通知はすべて Apple Push Notification service(APNs)を経由します。サーバーがスマホへ直接接続してデータを送ることはできません。スマホは Apple との長期接続を 1 本維持しています。サーバーは Apple の開発者アカウントで発行された鍵を使い、HTTP/2 で APNs に各メッセージを送信します。APNs はそのメッセージをスマホの既存の接続経由で配信します。
つまり、スタックの途中に APNs へ送信できる仲介役が必要です。スマホがあなたのサーバーをポーリングすることはないため、LAN 内に置いただけの Webhook エンドポイントは届け先がありません。配信経路の詳細は iPhone にプッシュ通知が届く仕組み を参照してください。
自前で送信元を運用するのは見た目以上に大変
APNs へ自分で接続することもできます。そのためには、署名鍵(トークン認証用の .p8 ファイル。毎年の期限切れはありません)または各アプリの TLS クライアント証明書(こちらは期限があります)、登録済みのアプリ、デバイストークンの保存方法、そして APNs のエラーや再試行を処理するコードが必要です。さらに、デバイスを登録して通知を表示する iOS アプリも必要になります。どれも単独なら扱えますが、鍵のローテーションや Apple のポリシー変更があってもすべてを動かし続けることこそが本当のコストです。
多くのセルフホストユーザーが必要としているのは配管ではなく結果です。APNs 側をすでに運用しているホスト型サービスを使えば、スタックはシンプルなままで、通知 1 件につき HTTP リクエスト 1 回で済みます。
集中モード、ミュート、割り込みレベル
iOS は、各通知の割り込みレベル、集中モードの設定、アプリの設定に基づいて、通知をどの程度目立たせて届けるかを決めます。アラートに関係するのは次の 3 点です。
- アプリで通知が許可されている必要があります。 まず iOS の設定でこれを確認してください。通知がオフのアプリには、サーバー側がどう動いていても通知は表示されません。
- 時間に敏感な通知は集中モードを突破できます。 Pocket Alert では
highのメッセージが時間に敏感な通知として届きます。より低いレベルは集中モードが終わるまで待機します。 - 重大な通知はサイレントスイッチとおやすみモードを無視します。 これには Apple が審査後に付与する特別な権限が必要です。Pocket Alert はこの権限を取得しています。有料プランの
criticalメッセージは、アプリに重大なアラートを許可していれば、スマホがミュートされていても音が鳴ります。この許可をオフにしている場合は、時間に敏感な通知として届きます。
レベルの設定方法は後述の優先度のセクションで説明します。
確実に届く設定の全体像
スタックが問題を検知し、HTTP リクエストを 1 回送信します。そのあとはホスト型サービスが処理します。
Grafana / Uptime Kuma / n8n / cron + CLI
│ HTTPS (API call or webhook)
▼
Pocket Alert ──► APNs ──► iPhone (Pocket Alert app)
役割分担は次のとおりです。
| あなたのスタックの役割 | Pocket Alert の役割 |
|---|---|
| 障害を検知し、何が重要かを判断する | リクエストを受け取り、API キーまたは Webhook URL を確認する |
| テキストを整形するか、独自の JSON を送る | フィールドをマッピングし、優先度レベルを設定して APNs へ配信する |
| イベントが発生したときに 1 回だけ送信する | アカウント内のすべてのデバイス、または指定したデバイスへプッシュする |
| 独自のログを保持する | メッセージ履歴と Webhook ごとのリクエストログを保持し、何が届き、何が失敗したかを確認できるようにする |
curl で最初の通知を送る
pocketalert.app/signup で新規登録し、API キー を開いて Create New Key をクリックします。キーは一度しか表示されないため、安全な場所にコピーしてください。
環境変数に保存して、メッセージを送信します。
export PA_KEY="YOUR_API_KEY"
curl -X POST "https://api.pocketalert.app/v1/messages" \
-H "Token: $PA_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Backup finished",
"message": "nightly-backup on nas01 completed in 14m",
"level": "high"
}'
成功すると、tid、title、message、application、device、created_at を含む JSON が返ります。あとでプッシュ通知とログの行を照合したい場合は、tid を保存しておいてください。
つまずきやすいポイントは次の 3 つです。
- Content-Type を指定してください。 API は JSON または
multipart/form-dataを受け付けます。application/x-www-form-urlencodedは拒否されます。これはヘッダーを省略したときにcurl -dが送る形式です。JSON ボディの場合は-H "Content-Type: application/json"を使い、フォームフィールドの場合は-Fを使ってください。 titleとmessageは必須です。 それ以外はすべて省略可能です。- すべてのデバイスに届けるには
device_idを省略してください。 スマホを複数お持ちで特定の端末に送りたい場合にのみ追加します。
コマンドラインからアラートを送る
Pocket Alert CLI は、既存のスクリプトにアラートを組み込むのに最も手早い方法です。シェルスクリプト、Homebrew、Go のいずれかでインストールできます。
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest
pocketalert auth を一度実行し、キーを貼り付けてください。キーは ~/.pocketalert/config.json に保存され、読み取れるのはあなただけです。サーバー、コンテナ、CI では、代わりに POCKETALERT_API_KEY を設定してください。
メッセージを送信します。
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
コマンドの出力をそのままアラートに流すこともできます。
df -h | pocketalert send "Disk report" --level default
または exec でコマンドをラップします。通常どおりコマンドを実行し、終了ステータス、実行時間、出力の最後の数行を含むプッシュ通知を 1 件送信し、終了コードはそのまま引き継ぎます。
pocketalert exec -t "Database dump" -- ./dump.sh
-q を付けるとメッセージ ID だけを出力するので、スクリプトで便利です。どのコマンドにも --json を付ければ、機械で読み取りやすい出力になります。
フィールドマッピング付きの Webhook
送信元がすでに JSON を送っている場合(Grafana、Uptime Kuma、独自サービスなど)、送信側のコードを書く必要はありません。Webhook のコンソールで Webhook を作成すると、https://p4a.me/wh/1234abcd のような受信 URL が発行されます。スラッグは推測できない形式で、各 URL は 1 つの Webhook と 1 つのアプリケーションに紐づきます。送信元からこの URL へ POST を送ってください。
プッシュ通知のタイトルは「Webhook」に Webhook の名前を加えた形になります。送信元がわかるように、たとえば Grafana のように名前を付けてください。メッセージテンプレートでは、GJSON パスを使って受信した JSON から値を取り出します。
- ネストしたフィールドには
%object.field% - 配列の要素には
%items.0.name% - 件数には
%users.#% - テンプレート全体を
*にすると、ボディ全体が送信されます
たとえば、次のような受信ペイロードに対するテンプレートは以下のようになります。
{
"service": "api-gateway",
"check": "tls-expiry",
"state": "warning",
"detail": "certificate expires in 6 days"
}
テンプレートは次のように書けます。
[%state%] %service%: %check%
%detail%
パスが存在しないプレースホルダーは空文字列として描画されます。そのため、入力ミスはエラーにはならず、テキストの空白として現れます。
テンプレートを書く前に、実際のペイロードを取得してください。Webhook テスター を開き、テスト用 URL をコピーして送信元の送信先に設定します。テスターにはメソッド、ヘッダー、ボディが表示されるので、送信元が実際に送るデータに合わせてパスを書けます。本番の機密情報を公開のテスト URL に送らないでください。URL を知っている人なら、そこに届いた内容を誰でも読めてしまいます。
優先度の設定には 2 つの方法があります。Webhook にデフォルトレベルを設定するか、ペイロードのトップレベルに level フィールドを含めます。level の値がデフォルトより優先されます。有効な値は silent、low、default、high、critical、または数値の -2 から 2 です。無効な level は無視され、Webhook のデフォルトが適用されます。
連携
Grafana のアラート
コンソールで、次のメッセージテンプレートを使って Grafana という名前の Webhook を作成します。
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
受信 URL をコピーします。Grafana では Alerting → Contact points → Add contact point に進み、Webhook 連携を選択して、次のように設定します。
Integration: Webhook
URL: https://p4a.me/wh/1234abcd
Method: POST
コンタクトポイントを通知ポリシーに紐づけると、該当するアラートがそこへルーティングされます。その後、コンタクトポイントの Test ボタンを押してください。severity="critical" ラベルを持つ HighCPU というアラートが発火すると、[firing] HighCPU (critical) と表示されます。解消されると、同じプッシュ通知が角かっこ内に resolved を付けて届きます。
注意点は 3 つあります。ルールで severity ラベルを設定していない場合、その部分は空になります。テンプレートが読み取るのはグループ内の最初のアラート(alerts.0)だけなので、1 件の通知に複数のアラートがまとまっている場合は、最初の概要しか表示されません。さらに、各ルールの保留期間(たとえば 5 分)は、値が上下を繰り返すメトリクスで毎分スマホを鳴らさないようにする最も手軽な方法です。詳しいフィールドについては Grafana ガイド を参照してください。
Uptime Kuma
Uptime Kuma は、ステータスが変わるたびに Webhook を送信します。種類 Webhook の通知を追加し、Post URL に受信 URL を設定して、リクエストボディは JSON プリセットのままにしてください。
Pocket Alert では、テンプレートに %msg% を使います。msg は、証明書の警告やテストメッセージを含め、Uptime Kuma が送るすべてのリクエストに含まれる唯一のフィールドです。すでに「[Website] [🔴 Down] timeout of 4000ms exceeded」のような読みやすい文になっています。Webhook のデフォルトレベルは high に設定してください。
プリセットのボディを使うと、Uptime Kuma は独自に level フィールドを追加しないため、復旧通知も障害通知と同じ強さで届きます。down には high、up には low を送るカスタムボディの例は Uptime Kuma ガイド を参照してください。
n8n
n8n のワークフローでは、問題を検知するステップの後に HTTP Request ノードを追加します。
- Method:
POST - URL:
https://api.pocketalert.app/v1/messages - Authentication: Generic Credential Type、次に Header Auth。名前は
Token、値に API キーを設定します。 - Send Body: オン、Body Content Type は JSON、Specify Body は Using JSON。オブジェクト全体を組み立てる式を入力します。
{{ JSON.stringify({
title: 'Disk almost full on ' + $json.host,
message: $json.detail,
level: 'high'
}) }}
JSON.stringify は値の中の引用符や改行をエスケープします。一方、JSON の文字列の中に "{{ $json.detail }}" と直接書く方法ではそれができません。すべてのワークフローの失敗を通知したい場合は、Error Trigger で始まるエラーワークフローを設定してください。失敗したワークフロー名は $json.workflow.name に、エラーは $json.execution.error.message に入ります。インポートしてすぐ使えるワークフローは n8n ガイド にあります。
定期的なチェック
cron ジョブは静かに失敗します。アラートを見逃すのが最も困るタイミングです。アラートはジョブそのものに組み込んでください。
POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh
cron はシェルのプロファイルを読み込まないため、先頭の 2 行でジョブにキーと、CLI を含む PATH を与えています。成功した実行は、既定レベルで「✓ Nightly backup」として届きます。失敗した実行は、high で「✗ Nightly backup (exit 1)」として届き、メッセージには出力の最後の数行が含まれます。失敗時だけ知らせてほしい場合は --on failure を追加してください。
exec が知らせてくれるのは、ジョブが失敗したときです。ジョブが実行されなかったときは検知できません。それには、cron ジョブ監視ガイド にあるように、デッドマンズスイッチと組み合わせてください。
スケジュールに自信がない場合は、無料の cron 式ツール に貼り付けてください。各フィールドを平易な英語に変換し、次の実行時刻の一覧を表示します。次回実行時刻はブラウザのタイムゾーンで表示されるため、サーバーのタイムゾーンとは異なる場合があります。
優先度レベルと重大なアラート
静かなものから大きなものまで、5 段階のレベルがあります。
| レベル | 値 | iPhone での表示 | 典型的な用途 |
|---|---|---|---|
silent | -2 | 音なし、通知センターへ直接表示 | 「解決済み」のイベント、後で確認すればよいログ |
low | -1 | 控えめに表示、画面は点灯しない | 情報提供 |
default | 0 | 音付きの通常の通知 | 定期的な結果、たとえばバックアップの完了 |
high | 1 | 時間に敏感、集中モードを突破 | 早めの対応が必要 |
critical | 2 | 重大なアラート、ミュート中も音が鳴る | 今すぐ対応が必要。有料プランのみ |
無料プランでは、critical のメッセージは high として配信されます。それでも時間に敏感な通知としてすぐに届きますが、ミュートスイッチには従います。
発火したアラートとその解消に対する妥当なマッピングは次のとおりです。
- 発火時:
high。ただし、起こされる価値がある少数のものにはcritical - 解消時:
silent
Webhook のデフォルトレベルで設定するか、送信元が送れる場合はペイロードの level フィールドで設定してください。
チェックリスト:アラートが届くことを確認する
- iOS の設定で Pocket Alert アプリの 通知を許可 してください。時間に敏感な通知を含め、有料プランなら重大なアラートも許可します。
- 集中モードをオンにしてテストします。 使用している集中モードをオンにし、上記の curl コマンドで
highのテストを送信して、通知が届くことを確認してください。届かない場合は、その集中モードのアプリの通知設定を確認してください。 - リクエストが Pocket Alert に届いたことを確認します。 API のメッセージはアプリとウェブコンソールのメッセージ履歴に表示されます。Webhook の呼び出しは、拒否されたものを含めて、その Webhook のリクエストログに表示されます。呼び出しが記録されていれば、問題はスマホ側にあります。記録されていなければ、問題は送信元にあります。
- 送信元のログを確認します。 送信リクエストの URL、ステータスコード、レスポンスボディを確認してください。
- 1 日の上限を確認します。 無料プランでは 1 日 50 件まで通知を送れます。値が上下を繰り返すチェックは 1 時間でその上限を使い切ることがあるため、規模を拡大する前に閾値と保留期間を調整してください。
pocketalert usageで、今日あと何件送れるかを確認できます。
それでもアラートが届かない場合は、次の順番で確認してください。送信元のログ、次に Pocket Alert の履歴、最後にレベルとデバイスの設定です。この順番で確認すると、どこで失敗しているかをすばやく特定できます。
よくある質問
Q. Apple の開発者環境を自分で用意しなくても、iPhone にプッシュ通知を送れますか?
はい、送れます。APNs にすでに接続しているホスト型サービスが Apple 側の処理を担当します。API キーを付けて HTTP リクエストを送ると、サービスがその iPhone アプリへ配信します。自前で送信元を運用するには、署名鍵、アプリの登録、独自の iOS アプリが必要です。
Q. セルフホストのアラートが遅れて届く、またはまったく届かないのはなぜですか?
主に次の 3 つのどれかが原因です。アプリで通知が許可されていない、有効な集中モードがアラートのレベルを抑えている、またはリクエストがサービスに到達していない。まずメッセージ履歴か Webhook のログを確認して、どれに当たるかを特定してください。
Q. 集中モードがオンでも、アラートは届きますか?
通知が許可されていれば、high のメッセージは時間に敏感な通知として届き、集中モードを突破できます。有料プランの critical のメッセージは、スマホがミュートされていても音が鳴るところまで対応します。より低いレベルは待機します。頼る前に、自分の集中モードの設定を必ずテストしてください。
Q. 無料プランはありますか?
はい。無料プランには、1 日 50 件の通知、デバイス 1 台、アプリケーション 1 つ、Webhook 1 つが含まれます。無料プランでは、重大なメッセージは高い優先度で配信されます。
次のステップ
約 5 分で、最初の iPhone 通知を受け取れます。
これがうまくいったら、実際の送信元を 1 つつなげてみてください。Grafana のコンタクトポイント、Uptime Kuma の通知、cron ジョブのいずれかです。ほかのホームラボ用の送信元については、ホームラボのアラート と Proxmox ガイド を参照してください。そのほかの連携については、Webhook 通知 と Grafana アラート を参照してください。サービスを比較検討中であれば、代替サービスのページ で違いを確認できます。