Webhook を作成 POST
外部サービスからの通知を受け取るための新しい Webhook を作成します。
エンドポイント
POST https://api.pocketalert.app/v1/webhooks認証
必須
リクエストに次のいずれかのヘッダーを含めてください:
リクエスト
ヘッダー
| ヘッダー | 必須 | 説明 |
|---|---|---|
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)で指定します。詳しくは メッセージの優先度レベルをご覧ください。 |
actions | string | ❌ | アクションボタンの JSON テンプレート。メッセージのアクションと同じ形式ですが、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 を返します。
置き換え後、各ボタンはメッセージのアクションと同様に検証されます。このペイロードで無効になったボタン(URL フィールドが存在しない view ボタンなど)は単独で破棄され、他のボタンとメッセージは引き続き配信されます。
アクションボタンは有料機能です。無料プランでは、サーバー側で除去されたうえで、ボタンなしのメッセージが配信されます。
メッセージテンプレートの構文
受信 JSON から値を取り出すには %field.path% を使用します:
| テンプレート | 説明 |
|---|---|
* | JSON ペイロード全体を出力 |
%field% | トップレベルのフィールドを取り出す |
%object.field% | ネストされたフィールドを取り出す |
%array.0.field% | インデックスを指定して配列から取り出す |
%% | リテラルの %。% のように、直後に別の %cpu%%% が続く単語の直前でのみ必要です。% のように 90% on %host% の後にスペースが続く場合はそのまま記述します |
詳しい例は Webhook の設定をご覧ください。
リクエストの例
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
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
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
$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'];レスポンス
成功時のレスポンス
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"
}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 スラッグは既に使用されています |