Webhook
このページの内容 9セクション
Webhookを使うと、デバイス(AuthToken)やトンネルが接続または切断されたときに、Localtonetがご自身のURLを呼び出します。チームへの通知、サービスの再起動、独自のステータスページの更新などに使えます。
仕組み #
- Webhookはトークングループに属します。そのグループのAuthToken、それらのトークンのトンネル、またはその両方を、設定に応じて監視します。
- 監視対象のトークンまたはトンネルの状態が接続済みまたは切断済みに変わると、Localtonetは小さなJSONボディを付けたHTTP
POSTリクエストを、指定したURLに送信します。 - 通知を受けるイベントは、接続、切断、またはその両方から選べます。
始める前に #
- 監視したいAuthTokenを含むトークングループ。グループはマイトークンで作成します。AuthTokenをご覧ください。
- インターネットから到達でき、JSONボディ付きの
POSTリクエストを受け付けるHTTPまたはHTTPSのエンドポイント。 - ご自身のアカウントのダッシュボードです。チームのダッシュボードで作業している間は、Webhookのメニュー項目は表示されません。
Webhookを作成する #
-
Webhookを開く #
ダッシュボードのメニューでWebhookを開きます。
-
通知してほしい内容を選ぶ #
設定 動作 トークンWebhookを有効化 グループのAuthTokenが接続または切断されたとき、つまりそのデバイスのLocaltonetクライアントがオンラインまたはオフラインになったときに、リクエストを送信します。 トンネルWebhookを有効化 グループのAuthTokenに属するトンネルが接続または切断されたときに、リクエストを送信します。 接続時に送信 接続済みへの変化に対してリクエストを送信します。 切断時に送信 切断済みへの変化に対してリクエストを送信します。 認証トークングループ 監視するトークングループです。必須です。 Webhook URL Localtonetが呼び出すアドレスです。必須です。 2つのWebhookの種類のうち少なくとも1つと、2つの通知の種類のうち少なくとも1つをオンにしてください。
-
作成 #
作成を選びます。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と同じです。 |
ActionDate | Localtonetが変化を検知した日時です。 | 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による最小限の例です。
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をテストする #
- テスト用デバイスのAuthTokenを1つ、Webhookのトークングループに追加します。
- そのデバイスで、トークンを指定してLocaltonetクライアントを起動します。接続時に送信がオンの場合、エンドポイントは
TypeがToken、StatusがConnectedのリクエストを受け取ります。 - Ctrl + Cでクライアントを停止します。エンドポイントは、
StatusがDisconnectedのリクエストを受け取ります。 - トンネルWebhookを有効化がオンの場合は、マイトンネルでそのトークンのトンネルを開始、停止すると、トンネルのイベントが届きます。
まだ公開エンドポイントがない場合は、受信側をご自身のコンピューターで実行し、監視しているAuthTokenとは別のAuthTokenで、LocaltonetのHTTPトンネルとして公開してください。トンネルのリクエスト検査に、すべてのWebhook呼び出しが表示されます。ログと検査をご覧ください。
トラブルシューティング #
「Webhookの種類を1つ以上オンにしてください。」または「通知の種類を1つ以上オンにしてください。」
作成を選ぶ前に、トークンWebhookを有効化またはトンネルWebhookを有効化のどちらかと、接続時に送信または切断時に送信のどちらかをオンにしてください。
「グループは必須です!」
認証トークングループでトークングループを選んでください。一覧が空の場合は、マイトークンでグループを作成し、トークンを追加してください。
リクエストが届かない
デバイスのAuthTokenが、Webhookが監視するグループのメンバーであること、一覧で対応するスイッチが有効になっていること、URLがインターネットから到達できること(localhostやプライベートアドレスではないこと)を確認してください。URLは、ご自身でテストできます。
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に属している必要があります。