# Push alert iPhone yang andal dari stack self-hosted

> Mengapa push notification iPhone dari homelab sulit, seperti apa jalur yang andal, dan cara menghubungkan Grafana, Uptime Kuma, n8n, cron job, dan shell script ke notifikasi penting di ponsel Anda.

*04.11.2026*

<!-- source: https://pocketalert.app/id/blog/self-hosted-iphone-push-notifications -->

Alert Grafana Anda menyala pukul 3 pagi. Log server menunjukkan panggilan webhook berhasil. iPhone Anda tetap diam. Monitoring self-hosted sudah bagus dalam mendeteksi kegagalan. Yang sering gagal di sebagian besar setup homelab adalah saat pesan harus sampai ke ponsel.

Panduan ini menjelaskan mengapa push notification iPhone dari stack self-hosted sulit, seperti apa jalur yang andal, dan cara menghubungkan Grafana, Uptime Kuma, n8n, cron job, dan shell script. Alert pertama yang berfungsi memakan waktu sekitar lima menit.

## Mengapa push iOS gagal di setup self-hosted

### Hanya APNs yang bisa menjangkau iPhone

Setiap push ke iPhone melewati Apple Push Notification service (APNs). Server Anda tidak bisa membuka koneksi langsung ke ponsel dan mengirim data. Ponsel menjaga satu koneksi jangka panjang ke Apple. Server Anda mengirim setiap pesan ke APNs melalui HTTP/2, terautentikasi dengan kunci dari akun developer Apple Anda. APNs kemudian mengirimkannya lewat koneksi yang sudah ada di ponsel.

Artinya, stack Anda memerlukan pengirim yang mampu berkomunikasi dengan APNs di tengah. Ponsel tidak pernah melakukan polling ke server Anda, jadi endpoint webhook biasa di LAN tidak punya tujuan untuk mengirim pesan. Untuk penjelasan lebih dalam tentang jalur pengiriman, lihat [cara push notification sampai ke iPhone](/blog/how-push-notifications-work-apns-fcm).

### Menjalankan pengirim sendiri lebih rumit dari kelihatannya

Anda bisa berkomunikasi langsung dengan APNs. Anda memerlukan kunci penandatanganan (file `.p8` untuk token auth, yang tidak kedaluwarsa setiap tahun, atau sertifikat klien TLS per aplikasi, yang kedaluwarsa), aplikasi yang terdaftar, cara menyimpan device token, dan kode yang menangani error serta retry APNs. Anda juga memerlukan aplikasi iOS yang mendaftarkan perangkat dan menampilkan alert. Setiap bagian relatif mudah dikelola sendiri. Yang menjadi beban sebenarnya adalah menjaga semuanya tetap berfungsi melalui rotasi kunci dan perubahan kebijakan Apple.

Kebanyakan self-hoster hanya membutuhkan hasilnya, bukan instalasi pipanya. Layanan hosted yang sudah menangani sisi APNs membuat stack Anda tetap sederhana: satu request HTTP per alert.

### Fokus, senyap, dan tingkat interupsi

iOS memutuskan seberapa keras setiap notifikasi dikirim berdasarkan tingkat interupsinya, mode Fokus Anda, dan pengaturan aplikasi. Ada tiga hal yang penting untuk alert:

1. **Notifikasi harus diizinkan untuk aplikasi.** Periksa ini dulu di Pengaturan iOS. Aplikasi yang senyap tidak akan pernah menampilkan alert Anda, apa pun perilaku servernya.
2. **Notifikasi sensitif waktu bisa menembus Fokus.** Di Pocket Alert, pesan `high` masuk sebagai sensitif waktu. Level yang lebih rendah menunggu sampai Fokus berakhir.
3. **Critical alert mengabaikan tombol senyap dan Jangan Ganggu.** Fitur ini memerlukan entitlement khusus yang diberikan Apple setelah peninjauan. Pocket Alert memilikinya: pesan `critical` pada paket berbayar memainkan suara meskipun ponsel dalam mode senyap, selama Anda mengizinkan Critical Alerts untuk aplikasi. Jika izin itu dimatikan, pesan tersebut masuk sebagai sensitif waktu.

Bagian prioritas di bawah menjelaskan cara mengatur level tersebut.

## Seperti apa setup yang andal

Stack Anda mendeteksi masalah dan mengirim satu request HTTP. Layanan hosted mengambil alih dari sana:

```
Grafana / Uptime Kuma / n8n / cron + CLI
        │  HTTPS (API call or webhook)
        ▼
Pocket Alert  ──►  APNs  ──►  iPhone (Pocket Alert app)
```

Pembagian tugasnya seperti ini:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Stack Anda melakukan</th><th>Pocket Alert melakukan</th></tr></thead>
<tbody>
<tr><td>Mendeteksi kegagalan dan menentukan apa yang penting</td><td>Menerima request dan memeriksa kunci API atau URL webhook Anda</td></tr>
<tr><td>Memformat teks, atau mengirim JSON sendiri</td><td>Memetakan field, mengatur level prioritas, dan mengirim ke APNs</td></tr>
<tr><td>Mengirim event sekali, saat terjadi</td><td>Mengirim ke semua perangkat di akun, atau ke perangkat yang Anda tentukan</td></tr>
<tr><td>Menyimpan log sendiri</td><td>Menyimpan riwayat pesan dan log request untuk setiap webhook, sehingga Anda bisa melihat apa yang masuk dan apa yang gagal</td></tr>
</tbody>
</table>
</div>

## Kirim alert pertama dengan curl

Daftar di [pocketalert.app/signup](/signup), buka [kunci API](/account/apikeys), lalu klik **Create New Key**. Kunci hanya ditampilkan sekali, jadi salin dan simpan di tempat yang aman.

Simpan di variabel lingkungan lalu kirim pesan:

```bash
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"
  }'
```

Panggilan yang berhasil mengembalikan JSON dengan `tid`, `title`, `message`, `application`, `device`, dan `created_at`. Simpan `tid` jika Anda ingin mencocokkan push dengan baris log nanti.

Tiga hal yang sering membuat bingung:

- **Atur Content-Type.** API menerima JSON atau `multipart/form-data`. API menolak `application/x-www-form-urlencoded`, yang dikirim `curl -d` jika header dihilangkan. Gunakan `-H "Content-Type: application/json"` dengan body JSON, atau `-F` untuk field formulir.
- **`title` dan `message` wajib diisi.** Field lainnya bersifat opsional.
- **Hilangkan `device_id` untuk menjangkau semua perangkat** di akun. Tambahkan jika Anda punya lebih dari satu ponsel dan ingin mengirim ke ponsel tertentu.

## Kirim alert dari command line

[Pocket Alert CLI](/tools/cli) adalah cara tercepat untuk menghubungkan alert ke script yang sudah ada. Instal dengan shell script, Homebrew, atau Go:

```bash
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
```

Jalankan `pocketalert auth` sekali dan tempel kunci Anda. Kunci disimpan di `~/.pocketalert/config.json`, hanya bisa dibaca oleh Anda. Di server, container, dan CI, atur `POCKETALERT_API_KEY` sebagai gantinya.

Kirim pesan:

```bash
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
```

Alirkan output perintah langsung ke alert:

```bash
df -h | pocketalert send "Disk report" --level default
```

Atau bungkus perintah dengan `exec`. Perintah dijalankan seperti biasa, lalu mengirim satu push berisi kode keluar, durasi, dan beberapa baris terakhir output, serta meneruskan kode keluar tersebut:

```bash
pocketalert exec -t "Database dump" -- ./dump.sh
```

Gunakan `-q` untuk hanya mencetak ID pesan, yang berguna untuk scripting. Tambahkan `--json` ke perintah mana pun untuk output yang bisa dibaca mesin.

## Webhook dengan pemetaan field

Ketika sumber Anda sudah mengirim JSON, seperti Grafana, Uptime Kuma, atau layanan kustom, Anda tidak perlu menulis pengirim sendiri. Buat webhook di konsol pada [Webhooks](/webhooks), dan Pocket Alert akan memberi Anda URL penerima seperti `https://p4a.me/wh/1234abcd`. Slug-nya tidak mudah ditebak, dan setiap URL terikat pada satu webhook dan satu aplikasi. Arahkan sumber Anda ke URL itu dengan `POST`.

Push yang masuk akan berjudul "Webhook" ditambah nama webhook, jadi beri nama sesuai sumbernya, misalnya **Grafana**. Template pesan mengambil nilai dari JSON yang masuk dengan path GJSON:

- `%object.field%` untuk field bersarang
- `%items.0.name%` untuk item array
- `%users.#%` untuk jumlah
- `*` sebagai seluruh template akan mengirim seluruh body

Misalnya, template untuk payload masuk seperti ini:

```json
{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}
```

bisa berupa:

```
[%state%] %service%: %check%
%detail%
```

Placeholder yang path-nya tidak ada akan ditampilkan sebagai string kosong, sehingga salah ketik akan terlihat sebagai celah dalam teks, bukan sebagai error.

Sebelum menulis template, tangkap payload yang sebenarnya. Buka [penguji webhook](/tools/webhook), salin URL uji, lalu arahkan sumber Anda ke sana. Penguji menampilkan method, header, dan body, sehingga Anda bisa menulis path sesuai dengan yang benar-benar dikirim sumber Anda. Jangan kirim rahasia produksi ke URL uji publik. Siapa pun yang tahu URL itu bisa membaca apa yang masuk ke sana.

Prioritas bekerja dengan dua cara. Atur level default pada webhook, atau sertakan field `level` tingkat atas di payload, yang akan menimpa default. Nilai yang valid adalah `silent`, `low`, `default`, `high`, dan `critical`, atau angka `-2` sampai `2`. `level` yang tidak valid diabaikan dan default webhook yang berlaku.

## Integrasi

### Alert Grafana

Di konsol, buat webhook bernama **Grafana** dengan template pesan ini:

```
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
```

Salin URL penerimanya. Di Grafana, buka **Alerting → Contact points → Add contact point**, pilih integrasi **Webhook**, dan atur:

```
Integration: Webhook
URL:         https://p4a.me/wh/1234abcd
Method:      POST
```

Lampirkan contact point ke notification policy agar alert yang cocok diarahkan ke sana, lalu tekan tombol **Test** pada contact point. Alert yang aktif bernama `HighCPU` dengan label `severity="critical"` akan muncul sebagai `[firing] HighCPU (critical)`. Saat alert selesai, push yang sama masuk dengan `resolved` di dalam kurung.

Tiga catatan. Bagian `severity` kosong kecuali aturan Anda menetapkan label tersebut. Template hanya membaca alert pertama dalam satu grup (`alerts.0`), sehingga jika satu notifikasi menggabungkan beberapa alert, Anda hanya melihat ringkasan pertama. Dan periode pending pada setiap aturan (misalnya 5 menit) adalah cara termurah untuk mencegah metrik yang naik-turun membangunkan ponsel Anda setiap menit. [Panduan Grafana](/blog/how-to-integrate-grafana-into-pocketalert) membahas field lainnya.

### Uptime Kuma

Uptime Kuma mengirim webhook pada setiap perubahan status. Tambahkan notifikasi bertipe **Webhook**, atur **Post URL** ke URL penerima Anda, dan biarkan preset JSON sebagai body request.

Di Pocket Alert, gunakan `%msg%` sebagai template. `msg` adalah satu-satunya field yang ada di setiap request yang dikirim Uptime Kuma, termasuk peringatan sertifikat dan pesan uji, dan isinya sudah terbaca seperti "[Website] [🔴 Down] timeout of 4000ms exceeded". Atur level default webhook ke `high`.

Dengan body preset, pemulihan akan masuk sekeras gangguan, karena Uptime Kuma tidak menambahkan field `level` dengan sendirinya. [Panduan Uptime Kuma](/blog/uptime-kuma-notifications) menunjukkan body kustom yang mengirim `high` untuk down dan `low` untuk up.

### n8n

Dalam workflow n8n, tambahkan node **HTTP Request** setelah langkah yang mendeteksi masalah:

- **Method:** `POST`
- **URL:** `https://api.pocketalert.app/v1/messages`
- **Authentication:** Generic Credential Type, lalu Header Auth. Nama `Token`, nilai kunci API Anda.
- **Send Body:** aktif, **Body Content Type** JSON, **Specify Body** Using JSON, dengan ekspresi yang membangun seluruh objek:

```
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}
```

`JSON.stringify` mengescape tanda kutip dan baris baru pada nilai, yang tidak dilakukan oleh `"{{ $json.detail }}"` biasa di dalam string JSON. Untuk kegagalan di seluruh workflow, siapkan error workflow yang dimulai dengan **Error Trigger**: nama workflow yang gagal ada di `$json.workflow.name` dan error-nya di `$json.execution.error.message`. [Panduan n8n](/blog/n8n-push-notifications) menyediakan workflow siap impor.

## Pengecekan terjadwal dan berulang

Cron job gagal secara diam-diam, dan itu waktu terburuk untuk melewatkan alert. Letakkan alert di dalam job itu sendiri:

```bash
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 tidak memuat profil shell Anda, jadi dua baris di atas memberi job kunci dan `PATH` yang mencakup CLI. Eksekusi yang berhasil masuk sebagai "✓ Nightly backup" pada level default. Yang gagal masuk sebagai "✗ Nightly backup (exit 1)" pada `high`, dengan beberapa baris terakhir output di dalam pesan. Tambahkan `--on failure` jika Anda hanya ingin mendengar tentang kegagalan.

`exec` memberi tahu Anda saat job gagal, bukan saat job tidak pernah berjalan. Untuk itu, pasangkan dengan dead man's switch, seperti dalam [panduan monitoring cron job](/blog/cron-job-monitoring-healthchecks).

Jika Anda tidak yakin tentang sebuah jadwal, tempelkan ke [alat ekspresi cron](/tools/cron) gratis. Alat ini menerjemahkan setiap field ke bahasa sehari-hari dan menampilkan waktu eksekusi berikutnya. Waktu eksekusi berikutnya memakai zona waktu browser Anda, yang mungkin berbeda dengan zona waktu server.

## Level prioritas dan critical alert

Ada lima level, dari yang paling senyap hingga paling keras:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Level</th><th>Nilai</th><th>Di iPhone</th><th>Penggunaan umum</th></tr></thead>
<tbody>
<tr><th><code>silent</code></th><td>-2</td><td>Tanpa suara, langsung ke Notification Center</td><td>Event "Resolved", log yang mungkin Anda baca nanti</td></tr>
<tr><th><code>low</code></th><td>-1</td><td>Pasif, tidak menyalakan layar</td><td>Informasional</td></tr>
<tr><th><code>default</code></th><td>0</td><td>Notifikasi normal dengan suara</td><td>Hasil rutin, seperti backup yang selesai</td></tr>
<tr><th><code>high</code></th><td>1</td><td>Sensitif waktu, menembus Fokus</td><td>Perlu perhatian segera</td></tr>
<tr><th><code>critical</code></th><td>2</td><td>Critical Alert, berbunyi meskipun dalam mode senyap</td><td>Perlu perhatian sekarang. Hanya paket berbayar</td></tr>
</tbody>
</table>
</div>

Pada paket gratis, pesan `critical` dikirim dengan level `high`. Pesan tetap sampai segera sebagai sensitif waktu, tetapi menghormati tombol senyap.

Pemetaan yang masuk akal untuk alert yang aktif dan penyelesaiannya:

- firing: `high`, atau `critical` untuk segelintir hal yang layak membangunkan Anda
- resolved: `silent`

Atur ini dengan level default webhook, atau dengan field `level` di payload jika sumber Anda dapat mengirimkannya.

## Checklist: pastikan alert Anda sampai

1. **Izinkan notifikasi** untuk aplikasi Pocket Alert di Pengaturan iOS, termasuk Time Sensitive Notifications dan, pada paket berbayar, Critical Alerts.
2. **Uji dengan Fokus aktif.** Nyalakan mode Fokus yang Anda gunakan, kirim uji `high` dengan perintah curl di atas, dan pastikan pesan itu sampai. Jika tidak, periksa pengaturan notifikasi aplikasi untuk Fokus tersebut.
3. **Pastikan panggilan sampai ke Pocket Alert.** Pesan API muncul di riwayat pesan di aplikasi dan konsol web. Panggilan webhook, termasuk yang ditolak, muncul di log request webhook tersebut. Jika panggilannya ada, masalahnya ada di ponsel. Jika tidak ada, masalahnya ada di sumber Anda.
4. **Periksa log sumber** untuk request keluar: URL, kode status, dan body respons.
5. **Pantau batas harian.** Paket gratis mengizinkan 50 notifikasi per hari. Satu pengecekan yang naik-turun bisa menghabiskannya dalam satu jam, jadi atur ambang batas dan periode pending sebelum Anda memperbesar skala. `pocketalert usage` menampilkan berapa sisa Anda hari ini.

Jika alert masih belum sampai, telusuri langkahnya secara berurutan: log sumber, lalu riwayat Pocket Alert, lalu pengaturan level dan perangkat. Urutan ini dengan cepat mengisolasi titik yang gagal.

## FAQ

**Bisakah saya mengirim push notification ke iPhone tanpa pengaturan developer Apple sendiri?**
Bisa. Layanan hosted yang sudah terhubung ke APNs menangani sisi Apple. Anda mengirim request HTTP dengan kunci API, dan layanan tersebut mengirimkannya ke aplikasi iPhone-nya. Menjalankan pengirim sendiri memerlukan kunci penandatanganan, pendaftaran aplikasi, dan aplikasi iOS sendiri.

**Mengapa alert self-hosted saya terlambat atau tidak sampai sama sekali?**
Biasanya karena salah satu dari tiga hal: notifikasi tidak diizinkan untuk aplikasi, Fokus yang aktif menahan level alert, atau request tidak pernah sampai ke layanan. Periksa riwayat pesan atau log webhook terlebih dahulu untuk melihat mana yang berlaku.

**Apakah alert akan tembus saat Fokus aktif?**
Pesan `high` masuk sebagai sensitif waktu, yang bisa menembus Fokus setelah notifikasi diizinkan. Pesan `critical` pada paket berbayar lebih jauh lagi dan berbunyi meskipun ponsel dalam mode senyap. Level yang lebih rendah menunggu. Uji pengaturan Fokus Anda sendiri sebelum mengandalkannya.

**Apakah ada paket gratis?**
Ada. Paket gratis mencakup 50 notifikasi per hari, 1 perangkat, 1 aplikasi, dan 1 webhook. Pesan critical dikirim dengan prioritas high pada paket gratis.

## Langkah selanjutnya

Anda bisa mendapatkan alert iPhone pertama dalam sekitar lima menit:

1. [Daftar](/signup) dan instal aplikasi di iPhone Anda.
2. Buat kunci API di [kunci API](/account/apikeys).
3. Jalankan perintah curl dari panduan ini.

Setelah itu berfungsi, hubungkan satu sumber nyata: contact point Grafana, notifikasi Uptime Kuma, atau cron job. Untuk sumber homelab lainnya, lihat [alert homelab](/use-cases/homelab-alerts) dan [panduan Proxmox](/blog/proxmox-alerts). Untuk integrasi lainnya, lihat [notifikasi webhook](/use-cases/webhook-notifications) dan [alert Grafana](/use-cases/grafana-alerts). Jika Anda membandingkan opsi, [halaman alternatif](/alternatives) memaparkan perbedaannya.
