# Webhook 設定

受信した JSON ペイロードからデータを取り出すために、Webhook のメッセージテンプレートを設定する方法を説明します。

## メッセージテンプレートの構文

Webhook を作成するときは、受信した JSON データをどのように通知へ整形するかを決めるメッセージテンプレートを定義します。

### 基本パターン

| パターン | 説明 |
|---------|-------------|
| `*` | JSON ペイロード全体を出力します |
| `%field%` | トップレベルのフィールドを取り出します |
| `%object.field%` | ネストされたフィールドを取り出します |
| `%array.0%` | 配列の最初の要素を取得します |
| `%array.0.field%` | 配列の要素からフィールドを取得します |
| `%%` | リテラルの `%` を表します。`%` のように、直後に別の `%cpu%%%` が続く単語の直前でのみ必要です。`%` のように `90% on %host%` の後ろが空白の場合は、そのまま残ります |

プレースホルダーには空白を含めないため、通常の文章中のパーセント記号はそのまま残ります。`CPU over 90% on %host%` は `CPU over 90% on db-1` と表示されます。

## 例

### JSON ペイロードの例

次の受信 Webhook ペイロードを例にします。

```json
{
  "event": {
    "title": "New Order",
    "message": "A new order has been placed with ID 12345",
    "tags": ["order", "new"],
    "users": [
      {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
      {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
      {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
    ]
  }
}
```

### テンプレートの設定

**Full JSON**

```text
*
```

**Extracted Fields**

```text
Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%
```

### 出力結果

```
Title: New Order
Message: A new order has been placed with ID 12345
Tags: ["order","new"]
Users: {"age":44,"first":"Dale","last":"Murphy","nets":["ig","fb","tw"]}
First user: Dale Murphy
```

## よく使う連携

### GitHub Webhook

```text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%
```

### Sentry によるエラー追跡

アラートアクション（Issue アラート）として使う社内連携の場合：

```text
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%
```

`view` を指定した `%data.event.web_url%` ボタンを追加すると、Issue を開けます。従来の Webhooks プラグインは別のペイロードを送信します。その場合は `%project_name%: %event.title%` と `%url%` を使用してください。

### Grafana アラート

```text
⚠️ %state%: %title%

%message%

Status: %status%
```

### Uptime Robot

```text
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%
```

## 高度なパス構文

複雑な JSON の抽出には、[GJSON パス構文](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)を使用します。

### 便利なパターン

| パターン | 説明 |
|---------|-------------|
| `%users.#%` | 配列の項目数 |
| `%users.#.first%` | すべての `first` の値の配列 |
| `%users.@reverse%` | 配列の順序を逆にします |
| `%data.@pretty%` | JSON を整形して表示します |

> **Tip: 詳しく見る**
>
> 完全なドキュメント: [GJSON パス構文](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## 優先度

受信ペイロードには、プッシュの配信方法を制御するために `level` フィールドを含めることができます。値は名前（`silent`、`low`、`default`、`high`、`critical`）または整数（`-2`〜`2`）です。詳しくは [メッセージの優先度](https://info.pocketalert.app/api/messages/create.md#priority-levels) を参照してください。

解決の順序（最初に一致したものが使われます）：

1. 受信 JSON ペイロードの `level` フィールド
2. Webhook の `default_level`（Webhook 作成時に設定）
3. アプリケーションの既定レベル
4. `default`（通常）

直接 API と異なり、Webhook の入力は寛容です。認識されない `level` の値は拒否されず無視され（既定値にフォールバックします）、アラートが失われることはありません。

## アクションボタン

Webhook は、生成するすべての通知に最大 3 つのアクションボタンを付けられます。Webhook の作成時または更新時に `actions` フィールド（JSON 文字列）を設定してください。詳しくは [Webhook の作成 → アクションボタンのテンプレート](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template) を参照してください。

`label` と `value` では、メッセージテンプレートと同じ `%field.path%` プレースホルダーを使えます。そのため、受信ペイロードからボタンを組み立てられます。

```json
[
  { "type": "view", "label": "Open PR", "value": "%pull_request.html_url%" },
  { "type": "http", "label": "Merge", "value": "{\"url\":\"https://ci.example.com/merge/%pull_request.number%\",\"method\":\"POST\"}" }
]
```

置換後、各ボタンは検証されます（`type` は `view`／`http`／`copy` のいずれか。`view` と `http` には `http(s)` の URL が必要です）。レベルの解析と同様に、この処理も寛容です。無効になったボタンだけが単独で破棄され、他のボタンと通知は引き続き配信されます。

アクションボタンは有料機能です。無料プランでは取り除かれ、ボタンなしで通知が配信されます。

Webhook を作成したら、テストできます。

**cURL**

```bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
```

**JavaScript**

```javascript
await fetch('https://p4a.me/wh/YOUR_WEBHOOK_URL', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event: { title: 'Test', message: 'Hello World' }
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
```

**PHP**

```php
Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
    'event' => [
        'title' => 'Test',
        'message' => 'Hello World',
    ],
]);
```

これにより、設定したメッセージテンプレートを使ったテスト通知が、お使いのデバイスに送信されます。
