# Webhook を作成 (POST)

外部サービスからの通知を受け取るための新しい Webhook を作成します。

## エンドポイント

```
POST https://api.pocketalert.app/v1/webhooks
```

## 認証

> **Info: 必須**
>
> リクエストに次のいずれかのヘッダーを含めてください:
> - `Token: <your-api-key>` — [API キー](https://pocketalert.app/account/apikeys)から取得します
> - `Authorization: Bearer <jwt-token>` — [ログイン](https://info.pocketalert.app/api/user/login.md)から取得します

## リクエスト

### ヘッダー

| ヘッダー | 必須 | 説明 |
|--------|:--------:|-------------|
| `Token` | ✅ | API キー |
| `Authorization` | ✅ | `Bearer <jwt-token>` |

### ボディパラメータ

| パラメータ | 型 | 必須 | 説明 |
|-----------|------|:--------:|-------------|
| `name` | string | ✅ | Webhook の名前(例: "Sentry", "GitHub") |
| `url` | string | ❌ | 受信 URL `https://p4a.me/wh/{url}` のスラッグ。省略するとランダムな 20 文字のスラッグが生成されます。重複は不可で、使用済みのスラッグを指定すると `409` が返されます |
| `message` | string | ✅ | メッセージテンプレート(生の JSON を出力する場合は `*` を使用) |
| `application_id` | string | ❌ | メッセージを分類するためのアプリケーション TID |
| `device_id` | string | ❌ | 対象デバイスの TID(省略するとすべてのデバイスが対象) |
| `default_level` | string \| int | ❌ | ペイロードに優先度が指定されていない場合に、この Webhook からのメッセージに適用される既定の優先度。名前(`silent`, `low`, `default`, `high`, `critical`)または整数(`-2`〜`2`)で指定します。詳しくは [メッセージの優先度レベル](https://info.pocketalert.app/api/messages/create.md#priority-levels)をご覧ください。 |
| `actions` | string | ❌ | アクションボタンの JSON テンプレート。[メッセージのアクション](https://info.pocketalert.app/api/messages/create.md#action-buttons)と同じ形式ですが、`label`/`value` に受信ペイロードから解決される `%field.path%` プレースホルダーを含めることができます。JSON 文字列として保存されます。有料機能のため、無料プランでは除去されます。 |

### アクションボタンのテンプレート

`actions` を使うと、Webhook から生成される通知に最大 3 つのボタンを含めることができます。`%field.path%` のプレースホルダーは受信ペイロードの値で置き換えられます(メッセージテンプレートと同じ構文です):

```json
[
  { "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
  { "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]
```

テンプレートは保存時に検証されます。有効な `type` を持つボタンを最大 3 つまでの JSON 配列である必要があり、プレースホルダーを含まないボタンは完全に有効でなければなりません。満たさない場合はリクエストが `400` を返します。

置き換え後、各ボタンは[メッセージのアクション](https://info.pocketalert.app/api/messages/create.md#action-buttons)と同様に検証されます。このペイロードで無効になったボタン(URL フィールドが存在しない `view` ボタンなど)は単独で破棄され、他のボタンとメッセージは引き続き配信されます。

アクションボタンは有料機能です。無料プランでは、サーバー側で除去されたうえで、ボタンなしのメッセージが配信されます。

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

受信 JSON から値を取り出すには `%field.path%` を使用します:

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

詳しい例は [Webhook の設定](https://info.pocketalert.app/api/webhooks/settings.md)をご覧ください。

### リクエストの例

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Push",
    "message": "Push to %repository.name%: %head_commit.message%",
    "application_id": "s9h1ekk5xb46jikthl"
  }'
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub Push',
    message: 'Push to %repository.name%: %head_commit.message%',
    application_id: 's9h1ekk5xb46jikthl'
  })
});

const webhook = await response.json();
console.log('Webhook URL:', `https://p4a.me/wh/${webhook.url}`);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/webhooks',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'GitHub Push',
        'message': 'Push to %repository.name%: %head_commit.message%',
        'application_id': 's9h1ekk5xb46jikthl'
    }
)

webhook = response.json()
print(f"Webhook URL: https://p4a.me/wh/{webhook['url']}")
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/webhooks', [
    'name' => 'GitHub Push',
    'message' => 'Push to %repository.name%: %head_commit.message%',
    'application_id' => 's9h1ekk5xb46jikthl',
]);

$webhook = $response->json();
echo 'Webhook URL: https://p4a.me/wh/'.$webhook['url'];
```

## レスポンス

### 成功時のレスポンス

> **Tip: 201 Created**
>
> Webhook の作成に成功しました

| フィールド | 型 | 説明 |
|-------|------|-------------|
| `tid` | string | Webhook の一意な識別子 |
| `name` | string | Webhook の名前 |
| `url` | string | Webhook の URL スラッグ。外部サービスではこれを使用します |
| `message` | string | メッセージテンプレート |
| `actions` | string | アクションボタンの JSON テンプレート(未設定の場合は空) |
| `is_active` | boolean | Webhook が有効かどうか |

```json
{
  "tid": "kblf7mh9j8jjyeh4fx",
  "name": "GitHub Push",
  "url": "cs994rqfkk8ljngt",
  "message": "Push to %repository.name%: %head_commit.message%",
  "actions": "",
  "application_tid": "qm47b9pzxzx7applfd0",
  "device_tid": "",
  "is_active": true,
  "created_at": "01.09.2023 22:38:48"
}
```

> **Tip: Webhook の利用**
>
> 外部サービスで、次の URL に POST するように設定してください:
> ```
> https://p4a.me/wh/{url}
> ```

### エラーレスポンス

| ステータス | 説明 |
|:------:|-------------|
| `400` | Bad Request — `name` または `message` がない、`default_level` が無効、または `actions` テンプレートが無効です |
| `401` | Unauthorized — トークンが無効または指定されていません |
| `403` | Forbidden — ご利用のプランの Webhook 数の上限に達しています |
| `404` | Not Found — `application_id` または `device_id` が存在しません |
| `409` | Conflict — `url` スラッグは既に使用されています |
