# 让异常 直接推送到你的手机 。

> 通过推送通知接收 Sentry、Rollbar 和 Bugsnag 的异常告警。将错误追踪工具的 Webhook 指向 Pocket Alert，新问题出现后不到一秒就能收到通知。

<!-- source: https://pocketalert.app/zh/use-cases/error-tracking-alerts -->

最后更新：2026-08-11

当 Sentry、Rollbar 或 Bugsnag 捕获到新异常时，标题和严重程度会在一秒内推送到你的手机。在用户反馈之前，先捕获这个错误。

## 三步让错误告警抵达你的手机

1. **创建 Webhook** — 创建一个带有 GJSON 消息模板的 Pocket Alert Webhook，并复制它的接收 URL。
2. **连接错误追踪工具** — 将 URL 粘贴到 Sentry Internal Integration（或 Rollbar/Bugsnag Webhook）中，并将其附加到告警规则。
3. **映射并发送** — GJSON 会把 data.event.title、culprit、level 和 web_url 映射到你的推送通知中。下一个异常就会让你的手机震动。

## 从堆栈跟踪到锁屏

你的错误追踪工具本身就会发送 Webhook。Pocket Alert 会把它变成你无法错过的推送通知。

- **兼容所有错误追踪工具** — Sentry、Rollbar、Bugsnag、Honeybadger 和 Airbrake 在出现新 issue 时都会触发外发 Webhook。将它指向 Pocket Alert 即可完成设置。
- **使用 GJSON 映射字段** — GJSON 路径可以直接从载荷中提取 data.event.title、data.event.culprit 和 data.event.level，并放入你的推送通知。
- **级别和规则直接展示** — 在推送通知中直接显示错误级别和触发的规则，这样致命异常和警告的显示就会不同。
- **每个环境一个通道** — 每个应用都有独立的 Webhook URL，因此生产环境、预发布环境和特定服务各自保持在不同的通道中。
- **亚秒级送达** — 异常会在一秒内到达你的手机，远早于邮件摘要的发送时间。
- **Webhook URL 即密钥** — Webhook URL 通过 HTTPS 传输，相当于你的应用密钥。需要新的端点时，可以随时轮换。

## 将错误告警发送到你的手机

### 1. 创建 Pocket Alert Webhook

在 [Webhooks](https://pocketalert.app/zh/webhooks) 页面创建一个 Webhook，其 GJSON `message` 模板用于读取 Sentry issue 告警的载荷（所有数据都嵌套在 `data.event` 下）：

```
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sentry","default_level":"critical","message":"[%data.event.level%] %data.event.title%\n%data.event.culprit%\n%data.event.web_url%","application_id":"qm47b9pzxzxg"}'
```

你会获得一个入站 URL，格式如 `https://p4a.me/wh/1234abcd`。

### 2. 将 Sentry 指向该 URL

在 [设置 → Developer Settings → Internal Integration](https://docs.sentry.io/organization/integrations/integration-platform/webhooks/issue-alerts/) 中，将 Webhook URL 设为你的接收 URL，并启用 Alert Rule Action。然后创建一条 issue 告警规则，并将该集成添加为动作：

```
Webhook URL:  https://p4a.me/wh/1234abcd
Permissions:  Issue & Event (Read)
Action:       Alert Rule Action — enabled

Alerts → Create Alert → When a new issue is created
→ Then send a notification via [your integration]
```

Sentry 会 POST `{"action":"triggered","data":{"event":{"title":...,"culprit":...,"level":...,"web_url":...}}}`；上面的 GJSON 路径会将这些字段提取到推送通知中。

### 3. 其他错误追踪工具（Rollbar、Bugsnag）

Rollbar（设置 → Notifications → Webhook）和 Bugsnag（Integrations → Generic webhook）发送的载荷结构更扁平。请根据它们的字段调整模板，例如 Rollbar 使用 `%data.item.title%`，Bugsnag 使用 `%error.exceptionClass%`，并粘贴相同的接收 URL。

[Webhook 设置文档](https://info.pocketalert.app/api/webhooks/settings.html)中涵盖了所有 GJSON 路径和 Webhook 选项。

## 常见问题

### 如何在手机上收到错误告警？

在 Sentry 中创建一个 Internal Integration，将 Webhook URL 设为你的 Pocket Alert 接收 URL，并启用 Alert Rule Action，然后把它添加到一条 issue 告警规则中。规则触发时，Sentry 会 POST 该 issue，推送通知会在一秒内到达你的手机。

### 字段映射如何工作？

Sentry issue 告警的 Webhook 数据嵌套在 data.event 下。Pocket Alert 使用 GJSON 路径读取，因此你可以把 data.event.title 映射为通知标题，把 data.event.culprit 或 web_url 映射到正文中，推送通知会准确告诉你触发了哪个 issue。

### 能否显示错误级别和触发的规则？

载荷中包含 data.event.level（warning、error、fatal）以及 data.triggered_rule 中的规则名称。在你的 GJSON 消息模板中同时引用这两项，这样致命异常和警告的显示内容就会不同。

### 能否区分生产环境和预发布环境？

为每个环境分别创建一个应用。生产环境和预发布环境的 Webhook 会进入不同的通道，你可以静音预发布环境，而不影响生产环境。

### 需要安装 Agent 吗？

不需要。Pocket Alert 只接收你的错误追踪工具已经发送的 Webhook，无需安装任何 Agent 或 SDK。Sentry、Rollbar、Bugsnag、Honeybadger 和 Airbrake 都支持外发 Webhook。

### 生产环境的异常能否突破勿扰模式？

可以。在消息中添加 "level":"critical"，在 Android 上它会发送到专用的通知通道，并绕过勿扰模式，你只需授权一次勿扰访问权限。在 iPhone 上，high 和 critical 级别会作为时效性通知送达，并能突破专注模式。每条消息都支持从 silent 到 critical 的级别，因此预发布环境的警告可以保持安静，而生产环境的致命错误会把你唤醒。在免费套餐中，critical 会按 high 发送：依然即时送达，只是无法绕过勿扰模式。
