メインコンテンツへスキップ
見出し画像

「Callback URLって何?」でつまずいた電気エンジニアが、APIとWebhookを"電話"にたとえて整理してみた

    LINE WORKSに仕様書を送ると、1分以内にAIの要約が返ってくる。

    今、そんな仕組みを自分のPCで動かしています。


    画像

    作ったのは、製造業で働く電気エンジニアの私です。
    PLCのラダーは書けますが、WebのAPIやサーバーについては完全に素人でした。

    作っている途中で一番つまずいたのが、設定画面にあったこの一文です。

    「Callback URLを入力してください」

    Callback URLとは何なのか。
    なぜ自分のPCのアドレスを入れても動かないのか。
    調べても、エンジニア向けの説明ばかりで、なかなか頭に入ってきませんでした。

    この記事では、同じところでつまずいている人に向けて、API・Webhook・Callback URLの関係を「電話」にたとえて整理します。

    この記事でわかること

    • APIとWebhookの違い

    • Callback URLとは何か

    • 自分のPCに、外から通知が届かない理由

    • ngrokで「外からの入口」を作る考え方

    • 私が実際にハマった失敗と、その原因

    作ったもの:ファイルを送るとAIが要約して返してくれるBot

    仕組みはシンプルです。

    1. LINE WORKSのトークに、仕様書や議事録のファイルを送る

    2. 自分のPCが、そのファイルを「ルーム名/案件名」のフォルダに自動で保存する

    3. AI(Claude)がファイルを読んで要約する

    4. 要約をPDFにして、トークに返信する

    上の動画では、Excelの仕様書とPDFの議事録を2つ同時に送っています。
    送ってから2つ目の要約が届くまで、約45秒でした。

    ※動画のファイルは、撮影用に作った架空の案件です。

    要約は、ただ文章を短くしただけではありません。
    たとえば仕様書の要約では、次のようなところまで出してくれました。

    • 仕様書の本文では「手入力は不可」なのに、備考では「要協議」になっている、という食い違いの指摘

    • 予算から部品代を引いた、設計・工事に使える残りの金額

    • 設計に着手できるかどうかの判断と、先に確認すべき項目

    仕様書を受け取ったときに最初にやる「読み込み」と「気になる点の洗い出し」を、ほぼ自動でやってくれるイメージです。

    では、この仕組みがどうやって動いているのか。
    ここからが本題です。

    APIは「こちらから電話をかける」

    APIは、こちらから相手のサービスに電話をかけて、用件を頼む方法です。

    • 「このファイルをください」

    • 「このトークにメッセージを送ってください」

    電話をかけるのは、いつもこちら側です。
    自分のPCからLINE WORKSに電話をかけるのは、特に難しくありません。

    Webhookは「向こうから電話がかかってくる」

    一方のWebhookは、何かが起きたときに、相手のほうから電話をかけてきてくれる仕組みです。

    • 「今、トークにファイルが投稿されましたよ」

    APIだけでこれを知ろうとすると、「新しいファイルはありますか?」と何度も電話をかけて確認し続けることになります。
    Webhookなら、投稿があったその瞬間に向こうから知らせてくれます。

    Callback URLは「かけてきてほしい電話番号」

    ここでやっと、Callback URLの話です。

    向こうから電話をかけてもらうには、「ここにかけてください」という電話番号を先に伝えておく必要があります。
    それがCallback URLです。

    LINE WORKSの場合は、開発者向けの管理画面(Developer Console)で、Botの設定にこのURLを登録します。
    トークにファイルが投稿されると、LINE WORKSのサーバーがこのURLに「ファイルが来ました」という通知を送ってきます。

    ここで私はつまずきました。
    自分のPCの「電話番号」がわからなかったのです。

    自分のPCには、外から電話がかからない

    会社や自宅のPCは、ルーターやファイアウォールの内側にあります。
    電話でたとえると、内線番号はあるけれど、外線番号がない状態です。

    • 内側から外へ電話をかける(API)→ できる

    • 外から内側へ電話をかける(Webhook)→ 届かない

    APIでファイルを取りに行くことはできるのに、「ファイルが投稿された」という知らせは受け取れない。
    これが、Callback URLに自分のPCを登録しても動かない理由でした。

    ngrokで「外線番号」を借りる

    そこで使ったのが ngrok(エングロック) というサービスです。

    ngrokを起動すると、インターネット上に https://xxxx.ngrok-free.dev のようなURLが発行されます。
    このURLにかかってきた電話を、自分のPCに転送してくれます。
    つまり、外線番号を一時的に借りるようなものです。

    あとは、このURLの最後に /callback を付けて、LINE WORKSのCallback URLに登録するだけです。


    画像

    図のオレンジの矢印がWebhook(向こうから届く通知)、青の矢印がAPI(こちらからの依頼)です。
    外から入ってくるのはオレンジの矢印だけで、その入口をngrokが作っています。

    注意:入口を作るということは、誰でもノックできるということ

    ngrokのURLは、知っていれば誰でもアクセスできます。
    そのため、届いた通知が本当にLINE WORKSから来たものかを、署名(合言葉のようなもの)で必ずチェックしています。
    このチェックを省くと、誰かが偽の通知を送ってきても、そのまま処理してしまいます。

    私がハマった失敗:「Webhookが届かない」の正体

    ある日、トークにファイルを送っても何も起きなくなりました。

    まず疑ったのは、自分の書いたコードです。
    どこかを壊してしまったのかと思い、あちこち見直しました。

    ところが、ログを確認すると、LINE WORKSからの通知が1回も届いていませんでした。

    原因は、拍子抜けするものでした。

    PCを再起動したあと、受付役のサーバーもngrokも起動していなかった。

    電話でいえば、電話番号も解約されていて、電話を取る人もいない状態です。
    コードは何も壊れていませんでした。

    この経験から、「届かない」ときは次の順番で確認するようにしています。

    1. 電話を受ける人はいるか(PCのサーバーは起動しているか)

    2. 外線番号は生きているか(ngrokは起動しているか)

    3. 登録している電話番号は合っているか(Callback URLは今のngrokのURLと同じか)

    そしてこの失敗のあと、PCを起動したら自動で立ち上がり、途中で落ちても自動で復旧するように仕組みを作り直しました。
    今は、PCにログインするだけで全部が動き出します。

    まとめ

    • API:こちらから電話をかける(実際の役割:ファイルの取得、メッセージの送信)

    • Webhook:向こうから電話がかかってくる(実際の役割:「ファイルが投稿された」という通知)

    • Callback URL:かけてきてほしい電話番号(実際の役割:通知の届け先として登録するURL)

    • ngrok:外線番号を借りる(実際の役割:外から自分のPCに届く入口を作る)

    この4つの関係がわかると、「Callback URLを入力してください」という画面で手が止まることはなくなります。

    次回:実際の作り方をすべて公開します

    この記事では、仕組みの考え方をまとめました。
    次の記事(有料)では、このBotを実際に動かすまでの全手順をまとめています。

    • LINE WORKS Developer Consoleで必要な設定(どこで何を控えるか)

    • 通知を受け取るサーバーのコードと、署名チェックの方法

    • 投稿されたファイルを取得して、案件ごとのフォルダに分ける方法

    • Claudeで要約して、PDFでトークに返信する方法

    • ngrokのURLをCallback URLに自動で反映する方法

    • PCの起動時に自動で立ち上げ、落ちても自動で復旧させる方法

    • 実際にハマったつまずきポイント集

    続き(有料):【コード付き】LINE WORKSに送ったファイルを、自分のPCのClaudeが要約して返すBotの作り方|非ITの現場エンジニア版

    質問は、コメントかThreadsのDMでお気軽にどうぞ。

     
     

    masaki

     
     
    🏭FA設備の電気技術者。プログラミング未経験から、AIで仕事と雑務を自動化した記録を実体験で書いています。 Amazonのアソシエイトとして、masakiは適格販売により収入を得ています。 Threads:@masaki_fa.ai

    あなたへのおすすめ