# Sentry 告警推送到手机：错误推送通知，无需代码

> 将 Sentry 问题与指标告警以推送通知的形式发送到你的 iPhone 或 Android 手机。包括 Sentry 内部集成、一个 Pocket Alert Webhook、适用于真实数据格式的模板、「Open in Sentry」按钮，以及关于级别的实话实说。

*19.10.2026*

<!-- source: https://pocketalert.app/zh/blog/sentry-alerts-to-phone -->

Sentry 会在异常发生的那一刻捕获它。然后它会给你发邮件，或者发到一个 Slack 频道里，而这个频道还会收到部署消息、站会提醒和其他几百条信息。如果错误在凌晨两点出现，或者你不在电脑前，你往往要等到用户反馈才会知道。

Sentry 告警本可以做得更好，但 Sentry 自己并没有用于告警的推送应用。它能做的是在告警规则匹配时触发一个 Webhook。把它指向 Pocket Alert，每条告警都会变成你手机上的推送通知，包含错误标题、问题来源，以及一个可以打开该问题的按钮。无需服务器，也无需代码。

## 你需要准备

- 一个允许你创建集成和告警的 Sentry 组织。
- 一个 Pocket Alert 账户，并在你的 [iPhone 或 Android 手机](/get-app) 上安装应用。免费套餐包含一个 Webhook，这个配置只需要一个。
- 如果想使用「Open in Sentry」按钮，需要一个来自 [API 密钥](/account/apikeys) 页面的 API 密钥（下文详述）。

## Sentry 如何将告警发送到 Webhook

Sentry 有两种方式向 URL 发送告警 POST 请求，它们的 JSON 格式不同：

- **内部集成**（Sentry 推荐）。你创建一个带有 Webhook URL 的私有集成，并打开它的 **Alert Action** 开关。之后它会作为一个操作出现在你的告警中。问题告警会带着 `Sentry-Hook-Resource: event_alert` 请求头到达，错误信息位于 `data.event` 下；来自指标监控器的问题告警会以 `metric_alert` 形式到达，并在 `data.description_title` 中包含现成的标题。
- **Webhooks（旧版）**。项目设置下的一个按项目配置的插件。它仍然可用，但设置页面本身写明 Sentry 强烈推荐使用内部集成。它的负载是扁平结构：`project_name`、`culprit`、`level`、`url`、`triggering_rules`，以及原始的 `event`。

本指南使用内部集成，并在最后提供旧版 Webhook 的模板。

## 第一步：创建 Pocket Alert Webhook

Pocket Alert 会把每个 Webhook 推送的标题命名为 `Webhook <name>`，所以把它命名为 **Sentry**，锁屏上的标题就是「Webhook Sentry」。推送正文来自一个模板，它使用 `%path%` 占位符从 Sentry 的 JSON 中提取字段。

最快的方式是一次 API 调用，因为操作按钮模板只能通过 API 设置。它会创建带有消息模板、默认级别和「Open in Sentry」按钮的 Webhook，然后输出接收 URL：

```bash
jq -n \
  --arg msg $'%data.event.title%%data.description_title%\n%data.event.culprit%%data.description_text%\nRule: %data.triggered_rule%' \
  --arg act '[{"type":"view","label":"Open in Sentry","value":"%data.event.web_url%%data.web_url%"}]' \
  '{name: "Sentry", message: $msg, default_level: 1, actions: $act}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'
```

这个模板看起来有些奇怪，这是有意为之。一个 Sentry 集成只有一个 Webhook URL，问题告警和指标告警都会发送到这里。如果某个占位符的路径在负载中不存在，它就会渲染为空字符串，所以 `%data.event.title%%data.description_title%` 对问题告警显示错误标题，对指标告警显示告警标题。同样的技巧也让按钮在两种情况下都能指向正确的链接。对于问题告警，`Rule:` 会显示告警的名称；在指标告警中，这一行保持为空。

如果你更喜欢点击操作，可以在控制台的 [Webhooks](/webhooks) 页面创建：名称填 **Sentry**，**默认优先级**选择高，然后粘贴消息模板：

```text
%data.event.title%%data.description_title%
%data.event.culprit%%data.description_text%
Rule: %data.triggered_rule%
```

你会收到相同的推送，只是没有按钮。复制控制台显示的接收 URL（`https://p4a.me/wh/...`）。

## 第二步：在 Sentry 中创建内部集成

1. 在 Sentry 中进入 **Settings > Developer Settings**，新建一个集成，并选择 **Internal Integration**。
2. 为它取一个名字，例如「Pocket Alert」。
3. 将接收 URL 粘贴到 **Webhook URL** 中。
4. 打开 **Alert Action**。这个开关会让该集成出现在告警构建器中。
5. 保存。内部集成会自动安装到你的组织中，无需 OAuth 步骤。

其他 Webhook 订阅项（issue、error、comment）保持不勾选。Pocket Alert 会把它收到的每个请求都转换为一条推送，而这些资源会以几乎全是空行的推送形式到达。

## 第三步：让告警发送到它

Sentry 当前的告警构建器位于 **Monitors > Alerts > Create Alert**：

1. **Source**：你关心的项目，或特定的监控器。
2. **Environment**：选择 `production`，这样测试环境的噪音就不会打扰你的手机。
3. **When**：「A new issue is created」是经典选择。「An issue escalates」和「A resolved issue regresses」也值得添加。
4. **Then**：选择 **Send a notification via an integration**，然后选中「Pocket Alert」集成。
5. **Throttling**：设置为 30 分钟左右，避免一个高频问题每次事件都发送一条推送。

保存之前，点击 If/Then 模块上的 **Send Test Notification**。手机应在一两秒内收到一条标题为「Webhook Sentry」的推送。

## 手机上会收到什么

对于问题告警，Sentry 的负载把错误信息放在 `data.event` 下。以下是模板使用的字段，来自 Sentry 文档中的 `event_alert` 负载：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>字段</th><th>示例</th><th>用途</th></tr></thead>
<tbody>
<tr><th><code>data.event.title</code></th><td>ReferenceError: heck is not defined</td><td>推送的第一行</td></tr>
<tr><th><code>data.event.culprit</code></th><td>抛出错误的位置</td><td>第二行</td></tr>
<tr><th><code>data.triggered_rule</code></th><td>非常重要的告警！</td><td>触发的是哪条告警</td></tr>
<tr><th><code>data.event.web_url</code></th><td>https://sentry.io/organizations/…/issues/…/events/…/</td><td>「Open in Sentry」按钮</td></tr>
<tr><th><code>data.event.level</code></th><td>error</td><td>可选，见下文</td></tr>
</tbody>
</table>
</div>

指标告警没有 `data.event`。它的 `action` 为 `critical`、`warning` 或 `resolved`，`data.description_title` 已经包含状态，例如「Resolved: Too many errors」，下面是 `data.description_text`（「1000 events in the last 10 minutes」）。按钮使用 `data.web_url`。

想在文本中显示 Sentry 的级别？在模板中添加 `Level: %data.event.level%`。它只是文本；下一节会解释为什么它不会改变推送的提醒强度。

## 级别：究竟决定推送提醒强度的是什么

Pocket Alert 有五个级别：静默、低、默认、高和紧急。对于 Webhook，级别按以下顺序确定：传入 JSON 中的顶层 `level` 字段，然后是 Webhook 的默认级别，最后是应用的默认级别。

Sentry 的级别不会自动映射到这套体系，而且模板也无法转换取值：

- 内部集成的负载中没有顶层 `level`。Sentry 的级别位于 `data.event.level` 中，因此 Pocket Alert 会使用 Webhook 的**默认级别**。这就是为什么上面的 Webhook 创建时设置了 `default_level: 1`（高），在 iPhone 上它会显示为时间敏感通知，并能穿透专注模式。
- 旧版 Webhook 确实会发送顶层 `level`，但使用的是 Sentry 的取值：`fatal`、`error`、`warning`、`info`、`debug`。它们都不是 Pocket Alert 的级别，因此会被忽略，改用默认级别。告警仍然会送达。

如果生产环境中的致命错误应该把你叫醒，而其他情况保持高级别，就需要在 Sentry 端进行拆分。在付费套餐中，创建第二个名为「Sentry critical」的 Pocket Alert Webhook，并设置 `default_level: 2`，再创建第二个内部集成指向它。然后在同一个告警中使用两个 If/Then 模块：

- 模块 1：**If none** 满足：Event level equals `fatal`。**Then** 通知「Pocket Alert」集成。
- 模块 2：**If all** 满足：Event level equals `fatal`。**Then** 通知「Pocket Alert critical」。

紧急告警在 iOS 和 Android 上都能穿透勿扰模式（参见[优先级级别](https://info.pocketalert.app/features/priority-levels)）。这是付费功能：在免费套餐中，紧急告警会按高级别发送。

## 旧版 Webhook：如果你已经在使用

在 **Project Settings > Legacy Integrations** 下启用了 **Webhooks（旧版）** 的项目，可以将它指向同类型的 Pocket Alert Webhook。负载格式不同，因此请使用以下模板：

```text
%project_name%: %event.title%
%culprit%
Rule: %triggering_rules.0%
```

上面 API 调用使用的按钮模板如下：

```json
[{ "type": "view", "label": "Open in Sentry", "value": "%url%" }]
```

请使用 `%event.title%`，而不是顶层的 `%message%`。在旧版负载中，`message` 是事件的日志消息，对于普通异常来说它是空的。旧版插件只有在告警包含通知项目旧版集成的操作时才会发送，其设置页面上有一个 **Send Test Event** 按钮。

## 诚实的限制

- **所有推送使用同一个标题。** Pocket Alert 将 Webhook 推送的标题设为 `Webhook <name>`，错误信息放在正文中。如果你希望把错误作为推送标题，需要在 Sentry 和[消息 API](https://info.pocketalert.app/api/messages/create) 之间加一个小函数来转换。
- **没有签名校验。** 内部集成会用 `Sentry-Hook-Signature` 对请求签名，而 Pocket Alert 不会校验它。随机生成的接收 URL 就是密钥，所以不要公开发布它。如果泄露了，请删除该 Webhook 并重新创建。
- **仅支持 JSON。** 两种 Sentry 机制都发送 JSON，所以这里没有问题，但使用表单编码的发送方会被拒绝。
- **每日上限。** 免费套餐每天可投递 50 条消息。开启节流并只为生产环境设置告警时，这已经足够；但如果为「每个捕获的事件」设置告警，很快就会用完。

## 如果没有收到任何推送

- **查看 Webhook 历史。** 发送到你的 Pocket Alert Webhook 的每个请求都会记录请求头、正文、渲染后的消息和状态。如果请求在那里，问题出在模板；如果不在，说明 Sentry 根本没有发送。
- **检查 Alert Action 开关。** 没有打开它，该集成就不会出现在 **Send a notification via an integration** 下。
- **检查告警历史。** Sentry 中告警的详情页会列出最近的运行记录。环境或事件级别等过滤条件经常会排除你预期的事件。
- **推送中出现空行**，说明某个路径与负载不匹配。请与 Webhook 历史中的正文对比，字段名区分大小写。
- **没有按钮**，说明 URL 路径结果为空；无效的按钮会被丢弃，但消息仍会送达。

## 常见问题

### 我需要写任何代码吗？

不需要。Sentry 发送 Webhook，Pocket Alert 将其转换为推送。本指南中唯一的命令是可选的 API 调用，用于添加「Open in Sentry」按钮。

### 可以把生产环境和测试环境分开吗？

可以。按环境过滤告警，或者为每个环境创建一条告警，分别指向不同的集成和 Webhook，每个 Webhook 投递到各自的 Pocket Alert 应用，这样你就可以单独静音测试环境。

### 这适用于自托管的 Sentry 吗？

内部集成和告警操作本身就是 Sentry 的功能。只要自托管版本足够新、已经包含这些功能，并且能够通过互联网访问 `p4a.me`，它就可以用同样的方式发送到 Pocket Alert。

### Rollbar、Bugsnag 和其他追踪工具呢？

同样的方法适用于任何能向 URL 发送 JSON 的追踪工具，只需要更改模板中的路径。关于更大的图景，请参阅[错误追踪告警](/use-cases/error-tracking-alerts)；关于模板的工作方式，请参阅 [Webhook 工具](/tools/webhook)和[模板语法](https://info.pocketalert.app/api/webhooks/settings)。

### 这个是免费的吗？

Pocket Alert 的免费套餐包含一个 Webhook、一台设备和每天 50 条消息，对于小型应用的生产错误告警来说已经足够。

[免费注册账户](/signup)，把 URL 粘贴到 Sentry 中，下一个生产环境错误就会第一时间通知你。
