コンテンツへスキップ
Localtonet Localtonet ダッシュボード

Webhook

このページのヘルプ
このページの内容 9セクション
  1. 仕組み
  2. 始める前に
  3. Webhookを作成する
  4. Webhookを開く
  5. 通知してほしい内容を選ぶ
  6. 作成
  7. Webhookの一覧
  8. Localtonetが送信するリクエスト
  9. 配信
  10. 受信側のサンプル
  11. Webhookをテストする
  12. トラブルシューティング
  13. 関連ページ

Webhookを使うと、デバイス(AuthToken)やトンネルが接続または切断されたときに、Localtonetがご自身のURLを呼び出します。チームへの通知、サービスの再起動、独自のステータスページの更新などに使えます。

仕組み #

  • Webhookはトークングループに属します。そのグループのAuthToken、それらのトークンのトンネル、またはその両方を、設定に応じて監視します。
  • 監視対象のトークンまたはトンネルの状態が接続済みまたは切断済みに変わると、Localtonetは小さなJSONボディを付けたHTTP POSTリクエストを、指定したURLに送信します。
  • 通知を受けるイベントは、接続、切断、またはその両方から選べます。

始める前に #

  • 監視したいAuthTokenを含むトークングループ。グループはマイトークンで作成します。AuthTokenをご覧ください。
  • インターネットから到達でき、JSONボディ付きのPOSTリクエストを受け付けるHTTPまたはHTTPSのエンドポイント。
  • ご自身のアカウントのダッシュボードです。チームのダッシュボードで作業している間は、Webhookのメニュー項目は表示されません。

Webhookを作成する #

  1. Webhookを開く #

    ダッシュボードのメニューでWebhookを開きます。

  2. 通知してほしい内容を選ぶ #

    設定動作
    トークンWebhookを有効化グループのAuthTokenが接続または切断されたとき、つまりそのデバイスのLocaltonetクライアントがオンラインまたはオフラインになったときに、リクエストを送信します。
    トンネルWebhookを有効化グループのAuthTokenに属するトンネルが接続または切断されたときに、リクエストを送信します。
    接続時に送信接続済みへの変化に対してリクエストを送信します。
    切断時に送信切断済みへの変化に対してリクエストを送信します。
    認証トークングループ監視するトークングループです。必須です。
    Webhook URLLocaltonetが呼び出すアドレスです。必須です。

    2つのWebhookの種類のうち少なくとも1つと、2つの通知の種類のうち少なくとも1つをオンにしてください。

  3. 作成 #

    作成を選びます。Webhookがフォームの下の一覧に表示されます。

Webhookの一覧 #

各行には、トークンWebhook、トンネルWebhook、グループ名、URL、接続通知、切断通知が表示され、各スイッチは有効または無効で示されます。操作列の削除ボタンを押し、確認すると、Webhookが削除されます。

Webhookは編集できません。URL、グループ、スイッチを変更するには、削除して新しく作成してください。同じグループに複数のWebhookを作成することもできます。たとえば、接続用と切断用で別々のURLを設定できます。

Localtonetが送信するリクエスト #

項目値
メソッドPOST
コンテンツタイプapplication/json; charset=utf-8
ボディ下記の4つのフィールドを持つJSONオブジェクトです。
フィールド意味値
Idイベントの対象となるトークンまたはトンネルを識別します。TypeがTokenの場合:AuthTokenを識別します。TypeがTunnelの場合:トンネルの数値IDで、文字列として送信されます。APIでtunnelIdとして使うIDと同じです。
ActionDateLocaltonetが変化を検知した日時です。ISO 8601形式の日付と時刻
Typeオブジェクトの種類です。TokenまたはTunnel
Status新しい状態です。ConnectedまたはDisconnected

トークンのイベント:

リクエストボディ
{
  "Id": "<YOUR_TOKEN>",
  "ActionDate": "2026-01-15T10:30:00.1234567+03:00",
  "Type": "Token",
  "Status": "Disconnected"
}

トンネルのイベント:

リクエストボディ
{
  "Id": "<TUNNEL_ID>",
  "ActionDate": "2026-01-15T10:31:12.7654321+03:00",
  "Type": "Tunnel",
  "Status": "Connected"
}

配信 #

  • 失敗した呼び出しは再試行されません。そのため、エンドポイントは常に利用可能で、すばやく応答するようにしてください。
  • リクエストには、署名やシークレットのヘッダーはありません。呼び出しがご自身のWebhookからのものであることを確認するには、URLに長いランダムな値(パスの一部やクエリパラメーターなど)を含め、受信側で確認してください。
  • 切断は、Localtonetがクライアントがいなくなったことを検知した時点で通知されるため、デバイスが接続を失った瞬間より少し遅れることがあります。
  • ActionDateは標準のISO 8601パーサーで解析し、含まれているオフセットを使ってください。タイムゾーンが固定だと決めつけないでください。

受信側のサンプル #

どのWebフレームワークでも構いません。受信側は、JSONボディを読み取り、成功ステータスで応答するだけで済みます。依存関係のないNode.jsによる最小限の例です。

receiver.js
const http = require('http');

http.createServer((req, res) => {
  let body = '';
  req.on('data', chunk => body += chunk);
  req.on('end', () => {
    if (req.method === 'POST' && req.url === '/localtonet/<YOUR_SECRET>') {
      const event = JSON.parse(body);
      console.log(event.Type, event.Status, event.ActionDate);
    }
    res.writeHead(200);
    res.end();
  });
}).listen(8080);

この受信側の場合、Webhook URLはhttps://<YOUR_HOST>/localtonet/<YOUR_SECRET>になります。

Webhookをテストする #

  1. テスト用デバイスのAuthTokenを1つ、Webhookのトークングループに追加します。
  2. そのデバイスで、トークンを指定してLocaltonetクライアントを起動します。接続時に送信がオンの場合、エンドポイントはTypeがToken、StatusがConnectedのリクエストを受け取ります。
  3. Ctrl + Cでクライアントを停止します。エンドポイントは、StatusがDisconnectedのリクエストを受け取ります。
  4. トンネルWebhookを有効化がオンの場合は、マイトンネルでそのトークンのトンネルを開始、停止すると、トンネルのイベントが届きます。

まだ公開エンドポイントがない場合は、受信側をご自身のコンピューターで実行し、監視しているAuthTokenとは別のAuthTokenで、LocaltonetのHTTPトンネルとして公開してください。トンネルのリクエスト検査に、すべてのWebhook呼び出しが表示されます。ログと検査をご覧ください。

トラブルシューティング #

「Webhookの種類を1つ以上オンにしてください。」または「通知の種類を1つ以上オンにしてください。」

作成を選ぶ前に、トークンWebhookを有効化またはトンネルWebhookを有効化のどちらかと、接続時に送信または切断時に送信のどちらかをオンにしてください。

「グループは必須です!」

認証トークングループでトークングループを選んでください。一覧が空の場合は、マイトークンでグループを作成し、トークンを追加してください。

リクエストが届かない

デバイスのAuthTokenが、Webhookが監視するグループのメンバーであること、一覧で対応するスイッチが有効になっていること、URLがインターネットから到達できること(localhostやプライベートアドレスではないこと)を確認してください。URLは、ご自身でテストできます。

Bash
curl -X POST "<YOUR_WEBHOOK_URL>" \
  -H "Content-Type: application/json" \
  -d '{"Id":"test","ActionDate":"2026-01-15T10:30:00+00:00","Type":"Token","Status":"Connected"}'
トークンのイベントは届くが、トンネルのイベントが届かない

WebhookのトンネルWebhookが有効になっていて、トンネルがグループ内のAuthTokenに属している必要があります。

サポート