Pythonの自動化結果をDiscordに通知する|Webhook URLの作り方と送信コード

自動化スクリプトを毎朝動かすようになると、次に気になるのが「ちゃんと終わったのかな?」ですよね。ログファイルを見に行けばわかるけれど、毎朝わざわざ開くのは、正直めんどうです。

そこでおすすめなのが、終わったら(失敗したら)Discordに通知を送り、スマホでも確認できる仕組みです。Discord なら、Webhook(ウェブフック)のURLを1つ作るだけで、Python から数行でメッセージを送れます。

💡
この記事で解決すること

Discord の Webhook URL を作り、Python の requests で「成功しました(○件)」「失敗しました(理由)」を送る関数を作ります。
Webhook URL は合言葉のようなものなので、コードには書かず環境変数から読みます。送りすぎ(429)や、URLが無効になったとき(404)の扱いもあわせて整理します。


この記事の前提

  • Discord のアカウントと、自分が管理できるサーバー(通知用に自分だけのサーバーを作るのがおすすめ)がある
  • requests を使ったことがある。まだの方は PythonでWeb APIのJSONを取得してCSVに保存する|requests入門 からどうぞ
  • この記事のコードは、Debian GNU/Linux 13 の Python 3.13.5 と requests 2.34.2 で、Discord と同じ応答(成功の 204、送りすぎの 429)を返す練習用のローカルサーバーに送って動作を確認しています。実際の Discord への送信画面は載せていません(掲載しているターミナル画像はローカルのモックです)

用語メモ
用語 ざっくりした意味
Webhook(ウェブフック) 「このURLにデータを送ると、チャンネルにメッセージが投稿される」という受け口。ボットを作らなくても使える
Webhook URL Webhook ごとに発行される専用のURL。中に秘密のトークンが入っているので、知られると誰でも投稿できてしまう
環境変数 パソコンやサーバーに覚えさせておく「名前つきの値」。コードに秘密の値を書かずに済む
204 No Content 「成功したけど、返す中身はないよ」というステータスコード
429 Too Many Requests 「送りすぎだから少し待ってね」というステータスコード

結論:URLは環境変数に、送信は関数1つにまとめる

流れはシンプルです。

  1. Discord で Webhook を作り、URLをコピーする
  2. URLを環境変数 DISCORD_WEBHOOK_URL に入れる
  3. Python から {"content": "メッセージ"} をPOSTする

PythonからWebhook URLへPOSTし、Discordのチャンネルに通知が届く流れ

手順1:Discord で Webhook URL を作る

Discord の公式ヘルプ Intro to Webhooks では、Webhook は次の流れで作ると説明されています。ボタン名は公式ヘルプ(英語)の表記です。日本語表示の画面では名前が違うことがあります。

  1. 通知を受けたいサーバーの Server Settings を開き、Integrations タブに進む
  2. 「Create Webhook」ボタンで新しい Webhook を作る
  3. 名前(例:自動化通知)を付け、投稿先のテキストチャンネルをドロップダウンで選ぶ
  4. 「Copy Webhook URL」ボタンでURLをコピーする

コピーしたURLは https://discord.com/api/webhooks/数字/長い文字列 のような形です。後ろの長い文字列がトークン(合言葉)なので、ブログやGitHub、AIへの質問に貼らないよう気をつけてください。


手順2:Webhook URL を環境変数に入れる

コードに直接書くと、うっかりGitHubに上げたときに誰でも投稿できてしまいます。ターミナルで環境変数に入れておきましょう。

Mac・Linux(bash や zsh)の場合:

  • 1
export DISCORD_WEBHOOK_URL='https://discord.com/api/webhooks/(ここにコピーしたURL)'

Windows の PowerShell の場合:

  • 1
$env:DISCORD_WEBHOOK_URL = 'https://discord.com/api/webhooks/(ここにコピーしたURL)'

どちらも、そのターミナルを閉じると消える一時的な設定です。毎回入れるのが大変なら、.env ファイルで管理する方法を APIキーをコードに直書きしない|.envと環境変数で安全に管理する(Python・GAS) で解説しています。


手順3:通知を送る関数を作る

次の内容を discord_notify.py として保存します。

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
"""Discord の Webhook に通知を送る。URL は環境変数 DISCORD_WEBHOOK_URL から読む。"""
import os
import sys
import time

import requests

MAX_LEN = 2000  # Discord の content は最大2000文字


class DiscordNotifyError(RuntimeError):
    """通知の失敗。メッセージには種類やステータスコードだけを入れ、URLは入れない。"""


def notify_discord(message: str) -> None:
    url = os.environ.get("DISCORD_WEBHOOK_URL")
    if not url:
        raise RuntimeError("環境変数 DISCORD_WEBHOOK_URL が設定されていません")

    payload = {
        "content": message[:MAX_LEN],
        "allowed_mentions": {"parse": []},  # @everyone などのメンションを無効にする
    }
    for attempt in range(2):  # 429(送りすぎ)のときだけ1回だけ待って再送
        try:
            res = requests.post(url, json=payload, timeout=10)
        except requests.RequestException as e:
            # requests の例外の文字列には Webhook URL(トークン入り)が入るので、種類だけにする
            raise DiscordNotifyError(f"Discord に接続できませんでした({type(e).__name__})") from None
        if res.status_code == 429 and attempt == 0:
            try:
                wait = float(res.json().get("retry_after", 1))
            except ValueError:  # 本文がJSONでないとき
                wait = 1.0
            wait = min(wait, 60)  # 長すぎる待ちはしない(60秒で打ち切り)
            print(f"送りすぎ(429)なので {wait:.1f} 秒待って再送します", file=sys.stderr)
            time.sleep(wait)
            continue
        if not res.ok:
            # raise_for_status() の例外にはURLが入るので使わず、ステータスコードだけにする
            raise DiscordNotifyError(f"Discord への通知に失敗しました(HTTP {res.status_code})")
        return  # 成功なら 204 No Content


if __name__ == "__main__":
    notify_discord("✅ テスト通知:Pythonから送信できました")
    print("送信しました")

python3 discord_notify.py を実行して、通知用チャンネルに「✅ テスト通知:Pythonから送信できました」が届けば成功です。練習用サーバーに向けて実行したときは、サーバー側に次の内容が届き、204 を返していました。

  • 1
  • 2
[mock] received: {"content": "✅ テスト通知:Pythonから送信できました", "allowed_mentions": {"parse": []}}
[mock] POST /api/webhooks/000/dummy-token HTTP/1.1 -> 204

コードのポイントです。

  • content が本文です。Discord の公式ドキュメントでは最大2000文字なので、message[:MAX_LEN] で切っています
  • "allowed_mentions": {"parse": []} は、本文に @everyone などが入ってもメンション(全員への通知)にしないための指定です。エラーメッセージの中身は自分で選べないので、入れておくと安心です
  • 成功すると、Discord は 204 No Content(中身なしの成功)を返します。それ以外の失敗は、ステータスコードだけを入れた DiscordNotifyError(RuntimeError の仲間)にしています。raise_for_status() や接続エラーの例外の文字列には Webhook URL(トークン入り)がそのまま入るため、ログやエラー表示にURLが残らないようにしています
  • 環境変数が空のときは、すぐにわかるエラーで止めます。試しに環境変数なしで動かすと、RuntimeError: 環境変数 DISCORD_WEBHOOK_URL が設定されていません で止まりました

送りすぎ(429)と、URLが無効(404)のとき

Discord の公式ドキュメント(Rate Limits)では、送りすぎると 429 が返り、何秒待てばよいかが Retry-After ヘッダーや本文の retry_after に入る、と説明されています。上のコードでは、429 のときに本文(JSON)の retry_after だけを読み、その秒数待って1回だけ送り直します。Retry-After ヘッダーは読んでいません(公式ドキュメントでは、どちらかの値に従えばよいとされています)。

練習用サーバーで「1回目だけ429を返す」ようにして試すと、次のように待ってから送り直し、2回目で成功しました。

  • 1
  • 2
送りすぎ(429)なので 1.5 秒待って再送します
送信しました

ローカルのモックで429のあと再送して204になったターミナル(実Discordへの送信結果ではありません)

逆に、404 が返ってきたら送り直してはいけません。Webhook が削除されたなどでURLが無効になっている状態で、公式ドキュメントにも「Webhook が404を返したら、もう使わないこと。繰り返すと一時的に制限される」と書かれています。上のコードは 404 を送り直さずにそのままエラーにするので、新しいURLを作り直して環境変数を差し替えてください。

通知はPOST(データを送る操作)なので、何度も自動で送り直すと、同じ通知が重複して届くことがあります。リトライの考え方は 外部APIの一時的な失敗に備える|Pythonのリトライと指数バックオフ(requests) にまとめました。


実践:毎日の処理の「成功・失敗」を知らせる

実際の自動化に組み込む例です。report_job.py として同じフォルダに保存します。daily_job の中身はダミーなので、自分の処理に置き換えてください。

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
"""毎日の処理の結果を Discord に知らせる例(中身はダミー)。"""
import logging
import sys

from discord_notify import DiscordNotifyError, notify_discord

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")


def daily_job() -> int:
    rows = [{"id": 1}, {"id": 2}, {"id": 3}]   # 本当はAPIやCSVから取ってくる想定のダミーデータ
    return len(rows)


def summary(e: Exception) -> str:
    """ログと通知に残す要点。例外の本文やトレースバックにはURLや秘密が混ざることがあるので、種類だけにする。
    DiscordNotifyError は、ステータスコードなど安全な内容だけを入れているのでそのまま使う。"""
    if isinstance(e, DiscordNotifyError):
        return str(e)
    return type(e).__name__


def main() -> int:
    try:
        count = daily_job()
    except Exception as e:
        # logging.exception は使わない(トレースバックに例外の本文が残るため)
        logging.error("daily_job で失敗しました(%s)", summary(e))
        try:
            notify_discord(f"❌ 毎日の集計が失敗しました({type(e).__name__})。詳細はログを確認してください")
        except Exception as ne:
            logging.error("Discord への通知にも失敗しました(%s)", summary(ne))
        return 1  # 処理の失敗
    logging.info("完了 %d件", count)
    try:
        notify_discord(f"✅ 毎日の集計が終わりました({count}件)")
    except Exception as ne:
        logging.error("処理は完了しましたが、Discord への通知に失敗しました(%s)", summary(ne))
        return 2  # 処理は成功、完了通知だけ失敗
    return 0


if __name__ == "__main__":
    sys.exit(main())

練習用サーバーに向けて実行すると、成功したときは「✅ 毎日の集計が終わりました(3件)」が届き、終了コードは 0 でした。daily_job が失敗したときは、通知には例外の種類(たとえば ValueError)だけが入り、終了コードは 1 になります。処理は成功したのに完了通知だけ失敗したときは、ログに残して終了コード 2 で終わるようにしています。終了コードは、0 が成功、1 が処理の失敗、2 が「処理は成功したが完了通知に失敗」です。

ここでのポイントは3つです。

  • 失敗したときは、ログにも通知にも例外の種類(通知の失敗ならステータスコード)だけを残す(詳しいログの残し方は Pythonの自動化スクリプトにログを残す|loggingで実行時刻・処理件数・エラーを記録する で解説しています)
  • 通知そのものが失敗しても、元のエラーが隠れないように、通知部分も try/except で包む
  • 失敗したら終了コード 1、完了通知だけ失敗したら 2 で終わる。cron などで動かしたときに「何が失敗したか」が記録に残るようにするためです

失敗の通知に、APIキーやパスワード、個人の情報が混ざらないようにも気をつけましょう。例外のメッセージには、処理中の値やアクセス先のURLがそのまま入ることがあります(requests のエラーには、URLが含まれることがあります)。そのため上のコードでは、通知にもログにも例外の種類だけを残し、logging.exception(トレースバックごと記録する書き方)は使っていません。ログファイルも、人に見せない場所に保存しましょう。

そのぶん、ログだけでは原因の細かい場所はわかりません。原因を調べるときは、手元で再現して確かめましょう。そのときに出たエラーやログをAIやSNS、チャットなどに貼るときは、先にURL、トークン、パスワードなどの秘密の情報を伏せてください(例:https://discord.com/api/webhooks/***/***)。

自分のスクリプトに組み込むときは、AIにこう頼むとスムーズです。

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
次のPythonスクリプトに、Discord への完了・失敗通知を組み込みたいです。

【条件】
- 送信は notify_discord(message) という関数を使う(中身は下に貼ります)
- Webhook URL は環境変数 DISCORD_WEBHOOK_URL から読む。コードには書かない
- 成功時は処理件数、失敗時は例外の種類だけを送る(例外のメッセージやURLは送らない)
- 失敗時はログに例外の種類だけを残してから通知し、終了コード 1 で終わる。完了通知だけ失敗したら終了コード 2 で終わる
- logging.exception やトレースバックは使わない(URLや秘密が残るため)
- 通知の送信に失敗しても、元のエラーが隠れないようにする

【notify_discord の中身】
(discord_notify.py を貼る)

【組み込みたいスクリプト】
(ここに貼る。URLやキー、個人情報は伏せる)

セキュリティの注意

  • Webhook URL は、そのURLだけで誰でも投稿できてしまう合言葉のようなものです。環境変数で管理し、コード、コマンドの履歴、スクリーンショット、ログ、通知の本文に残さないようにしましょう
  • エラーの内容をそのまま通知に流さず、秘密を含まない短い要点だけにします
  • URLが漏れたかもしれないときは、Discord で Webhook を削除して作り直してください
  • 429 が返ってきたら指定された秒数を守り、送り直す回数にも上限を付けましょう

参考:Rate Limits(Discord 公式ドキュメント)


つまずきやすい点

症状 原因 対処
環境変数 DISCORD_WEBHOOK_URL が設定されていません 別のターミナルで設定した、またはターミナルを閉じて消えた 実行するターミナルで設定し直す。cron では環境変数が引き継がれないことがあるので、毎朝の作業をPCを触らず動かしたい|cron入門(Pythonを定時実行) も確認する
400 Bad Request 本文が空、または送る形式が違う json=payload で送っているか、content が空でないかを見る
404 Not Found Webhook が削除された、URLの写し間違い 送り直さず、Webhook を作り直してURLを差し替える
429 Too Many Requests 短時間に送りすぎた ループの中で1件ずつ送らず、まとめて1通にする
通知に @everyone が反応してしまった メンションの抑止を入れていない allowed_mentions を指定する

エラーで困ったら、こんなふうに相談してみてください。

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
PythonからDiscordのWebhookにrequests.postで通知を送っています。
次のエラーになりました。原因の候補と、確認する順番を教えてください。

【エラーメッセージ】
(ここに貼る。Webhook URLは https://discord.com/api/webhooks/***/*** のように伏せる)

【送っているJSON】
{"content": "(本文)", "allowed_mentions": {"parse": []}}

まとめ

  • Discord の Webhook URL は、Server Settings の Integrations から作れる
  • URLは合言葉なので、コードではなく環境変数に入れる
  • {"content": ...} をPOSTし、成功なら 204
  • 429 は待って送り直し、404 は送り直さずURLを作り直す
  • 失敗通知は「短い要点だけ」。詳しくはログに残す

次の一歩は、今動かしている自動化スクリプトの最後に notify_discord を1行足して、完了通知を受け取ってみることです。GASで動かしている処理にも通知を付けたいなら、次の GASからSlackに通知する|Incoming WebhookのURLをスクリプトプロパティで安全に使う へどうぞ。


関連する本・記事

より詳しく知りたいときは、公式ドキュメントの Discord Webhook Resource、Discord Rate Limits、Intro to Webhooks(Discordヘルプ) も参考になります。