通知機能

[更新: 2026年04月21日]

高火力 DOK では、タスクの完了などのイベントの通知機能を提供しています。

はじめに 

高火力 DOK では、タスクの正常終了やエラー終了をトリガーに、ユーザーが登録した Webhook へ通知を送信する機能を提供しています。

機能概要 

この通知機能では、タスクの終了（正常完了・エラー）をトリガーに、ユーザーが登録した Webhook へ通知を送信します。

仕様 

サポートする通知方式 

Webhook

サポートする Webhook 形式 

形式	説明
Slack	Slack Incoming Webhook（blocks API 形式）
Discord	Discord Incoming Webhook（embeds 形式）
カスタム	ユーザーが設定したサーバへの Webhook

Webhookの送信フォーマット 

形式

ペイロード例

Slack

{
  "text": "タスク my-task が終了しました。\\nステータス: done\\n状況を確認するにはこちらをご覧ください\\nhttps://example.com/tasks/detail/abc-123",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*高火力DOK タスク終了通知*\\nタスク my-task が終了しました。\\nステータス: done\\n状況を確認するにはこちらをご覧ください\\nhttps://example.com/tasks/detail/abc-123"
      }
    }
  ]
}

Discord

{
  "content": "タスク my-task が終了しました。\\nステータス: done\\n状況を確認するにはこちらをご覧ください\\nhttps://example.com/tasks/detail/abc-123",
  "embeds": [
    {
      "title": "高火力DOK タスク終了通知",
      "description": "タスク my-task が終了しました。\\nステータス: done\\n状況を確認するにはこちらをご覧ください\\nhttps://example.com/tasks/detail/abc-123",
      "color": 3066993
    }
  ]
}

カスタム

{
  "text": "タスク my-task が終了しました。\\nステータス: done\\n状況を確認するにはこちらをご覧ください\\nhttps://example.com/tasks/detail/abc-123",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*高火力DOK タスク終了通知*\\nタスク my-task が終了しました。\\nステータス: done\\n状況を確認するにはこちらをご覧ください\\nhttps://example.com/tasks/detail/abc-123"
      }
    }
  ]
}

サポートする通知イベント 

タスク正常終了時
タスクエラー終了時

通知機能の使い方 

事前準備（Webhook URL の用意）

通知を受け取るには、あらかじめ Webhook URL を用意しておく必要があります。

Slack の場合は Incoming Webhooks を作成してください。
Discord の場合は Webhook の導入を参照してください。
カスタム Webhook の場合は、POST リクエストを受け取れるエンドポイントを用意してください。

通知先の登録手順 

高火力 DOK のコントロールパネルにログインします。

「設定」から「通知」ページに移動します。

「タスクの終了を通知する」を有効にします。

通知先に任意の Webhook URL を入力します。

Webhook URL を入力し、「テスト送信」をクリックすることで、送信先の確認が可能です。

保存をクリックして、通知先の保存を行います。

下記目玉マークをクリックすることで、シークレットの確認が可能です。

注釈

Slack, Discord 以外の Webhook URLを入力した場合、署名検証用の secret が生成されます。
Slack や Discord を選択した場合は secret は生成されません。

署名検証の設定方法（カスタム Webhook のみ）

カスタム Webhook を使用する場合、受信側で署名検証を行うことで、リクエストが高火力 DOK からのものであることを確認できます。

Python での署名検証サンプル:

import hmac
import hashlib

def verify_signature(secret: str, body: bytes, signature_header: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Node.js での署名検証サンプル:

const crypto = require("crypto");

function verifySignature(secret, body, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

注釈

secret は Webhook 登録時に生成される値です。
body はリクエストの本文（バイト列）です。
signature_header は X-Hub-Signature-256 ヘッダーの値です。

Web API による通知機能の設定方法 

Web API による通知機能の操作方法を解説します。

1. 通知設定の作成 

通知設定の作成を行います。
zone_id はゾーンIDを選択してください。詳細は、さくらのクラウドドキュメントを参照してください。
token, secret は APIキー管理を参照し、作成してください。

curl -u "<token>:<secret>" -X POST https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/notification/settings/ \
  -d '{"event_type": "task_completed", "is_enabled": true}'

通知設定の作成の Web API リクエスト時に下記のようなレスポンスがあります。
id の値を控えておきます。本稿では setting_id とします。

{
  "id": 1,
  "event_type": "task_completed",
  "is_enabled": true,
  "endpoints": []
}

2. 通知先の作成 

通知先の作成を行います。
address に送信したい通知先のURLを設定してください

curl -u "<token>:<secret>" -X POST https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/notification/endpoints/ \
-d '{"endpoint_type": "webhook", "address": "https://example.com/webhook"}'

通知先の保存の Web API リクエスト時に下記のようなレスポンスがあります。
id の値を控えてください。本項では endpoint_id とします。

{
  "id": 10,
  "endpoint_type": "webhook",
  "address": "https://example.com/webhook",
  "secret": "abc123..."
}

3. 通知設定と通知先の紐付け 

通知設定と通知先の紐付けを行います。
setting_id, endpoint_id を利用して、リクエストを送信します。

curl -u "<token>:<secret>" -X PATCH https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/notification/settings/<setting_id>/ \
  -d '{"endpoint_ids": [<endpoint_id>]}'

# 例:
# setting_id が 1, endpoint_id が 10 の場合
curl -u "<token>:<secret>" -X PATCH https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/notification/settings/1/ \
  -d '{"endpoint_ids": [10]}'

4. タスク作成 

タスクの作成を行います。
タスク作成Web API の詳細は Web API ドキュメントを参照してください。
今回はV100プラン(v100-32gb)を利用してタスクを作成します。

curl -u "<token>:<secret>" -X POST https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/tasks/ \
-d '{
  "name": "my-task",
  "containers": [
    {
      "image": "ubuntu:latest",
      "plan": "v100-32gb",
      "command": ["echo", "hello"]
    }
  ]
}'

タスク作成の際に下記のようなレスポンスがあります。
id の値を控えてください。本稿では task_id とします

{
"id": "00000000-0000-0000-0000-000000000000",
"name": "my-task",
"status": "waiting",
}

5. タスクと通知先の紐付け 

タスクと通知先の紐付けを行います。
task_id と endpoint_id をそれぞれを利用しリクエストを行います。

 curl -u "<token>:<secret>" -X PUT https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/tasks/<task_id>/notification-preference/ \
-d '{"is_enabled": true, "endpoint_ids": [<endpoint_id>]}'

# 例
# task_id が 00000000-0000-0000-0000-000000000000、endpoint_id が 10の場合
 curl -u "<token>:<secret>" -X PUT https://secure.sakura.ad.jp/cloud/zone/<zone_id>/api/managed-container/1.0/tasks/00000000-0000-0000-0000-000000000000/notification-preference/ \
-d '{"is_enabled": true, "endpoint_ids": [10]}'

注意事項・制限 

通知はバッチ処理で送信されるため、イベント発生から通知まで即時実行はされません。
通知先へのリクエストが失敗された場合、所定の回数リトライが実行されます。
登録できる通知先は 1 つだけです。
カスタム Webhook のみ、X-Hub-Signature-256 ヘッダーによる署名検証が可能です。
システムメンテナンス中など、一時的に通知が遅延または停止する場合があります。
レジストリのパーミッションエラーなど、タスク実行前に開始できなかったタスクの終了は通知されません。