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 ペイロードを例にします。
{
"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"]}
]
}
}テンプレートの設定
*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
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%Sentry によるエラー追跡
アラートアクション(Issue アラート)として使う社内連携の場合:
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%view を指定した %data.event.web_url% ボタンを追加すると、Issue を開けます。従来の Webhooks プラグインは別のペイロードを送信します。その場合は %project_name%: %event.title% と %url% を使用してください。
Grafana アラート
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%高度なパス構文
複雑な JSON の抽出には、GJSON パス構文を使用します。
便利なパターン
| パターン | 説明 |
|---|---|
%users.#% | 配列の項目数 |
%users.#.first% | すべての first の値の配列 |
%users.@reverse% | 配列の順序を逆にします |
%data.@pretty% | JSON を整形して表示します |
詳しく見る
完全なドキュメント: GJSON パス構文
優先度
受信ペイロードには、プッシュの配信方法を制御するために level フィールドを含めることができます。値は名前(silent、low、default、high、critical)または整数(-2〜2)です。詳しくは メッセージの優先度 を参照してください。
解決の順序(最初に一致したものが使われます):
- 受信 JSON ペイロードの
levelフィールド - Webhook の
default_level(Webhook 作成時に設定) - アプリケーションの既定レベル
default(通常)
直接 API と異なり、Webhook の入力は寛容です。認識されない level の値は拒否されず無視され(既定値にフォールバックします)、アラートが失われることはありません。
アクションボタン
Webhook は、生成するすべての通知に最大 3 つのアクションボタンを付けられます。Webhook の作成時または更新時に actions フィールド(JSON 文字列)を設定してください。詳しくは Webhook の作成 → アクションボタンのテンプレート を参照してください。
label と value では、メッセージテンプレートと同じ %field.path% プレースホルダーを使えます。そのため、受信ペイロードからボタンを組み立てられます。
[
{ "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 -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"event": {"title": "Test", "message": "Hello World"}}'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' }
})
});import requests
requests.post(
'https://p4a.me/wh/YOUR_WEBHOOK_URL',
json={'event': {'title': 'Test', 'message': 'Hello World'}}
)Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
'event' => [
'title' => 'Test',
'message' => 'Hello World',
],
]);これにより、設定したメッセージテンプレートを使ったテスト通知が、お使いのデバイスに送信されます。