コンテンツへスキップ

Webhook を作成 POST ​

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

エンドポイント ​

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

認証 ​

必須

リクエストに次のいずれかのヘッダーを含めてください:

  • Token: <your-api-key> — API キーから取得します
  • Authorization: Bearer <jwt-token> — ログインから取得します

リクエスト ​

ヘッダー ​

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

ボディパラメータ ​

パラメータ型必須説明
namestring✅Webhook の名前(例: "Sentry", "GitHub")
urlstring❌受信 URL https://p4a.me/wh/{url} のスラッグ。省略するとランダムな 20 文字のスラッグが生成されます。重複は不可で、使用済みのスラッグを指定すると 409 が返されます
messagestring✅メッセージテンプレート(生の JSON を出力する場合は * を使用)
application_idstring❌メッセージを分類するためのアプリケーション TID
device_idstring❌対象デバイスの TID(省略するとすべてのデバイスが対象)
default_levelstring | int❌ペイロードに優先度が指定されていない場合に、この Webhook からのメッセージに適用される既定の優先度。名前(silent, low, default, high, critical)または整数(-2〜2)で指定します。詳しくは メッセージの優先度レベルをご覧ください。
actionsstring❌アクションボタンの 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 の作成に成功しました

フィールド型説明
tidstringWebhook の一意な識別子
namestringWebhook の名前
urlstringWebhook の URL スラッグ。外部サービスではこれを使用します
messagestringメッセージテンプレート
actionsstringアクションボタンの JSON テンプレート(未設定の場合は空)
is_activebooleanWebhook が有効かどうか
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}

エラーレスポンス ​

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

Pocket Alert ドキュメント