본문으로 건너뛰기
Localtonet Localtonet 대시보드

웹훅

이 페이지 도움받기
이 페이지의 내용 섹션 9개
  1. 작동 방식
  2. 시작하기 전에
  3. 웹훅 만들기
  4. 웹훅 열기
  5. 알림 받을 대상 선택
  6. 생성
  7. 웹훅 목록
  8. Localtonet이 보내는 요청
  9. 전달
  10. 수신기 예시
  11. 웹훅 테스트
  12. 문제 해결
  13. 관련 페이지

웹훅을 사용하면 기기(AuthToken)나 터널이 연결되거나 연결 해제될 때 Localtonet이 내 URL을 호출합니다. 팀에 알리거나, 서비스를 재시작하거나, 자체 상태 페이지를 최신으로 유지하는 데 활용하세요.

작동 방식 #

  • 웹훅은 토큰 그룹에 속합니다. 선택한 대로 그룹의 AuthToken, 해당 토큰의 터널, 또는 둘 다를 감시합니다.
  • 감시 중인 토큰이나 터널의 상태가 연결됨 또는 연결 해제됨으로 바뀌면 Localtonet이 내 URL로 작은 JSON 본문이 담긴 HTTP POST 요청을 보냅니다.
  • 두 이벤트 중 연결됨, 연결 해제됨, 또는 둘 다 중에서 원하는 것을 선택합니다.

시작하기 전에 #

  • 감시할 AuthToken이 들어 있는 토큰 그룹. 그룹은 내 토큰에서 만듭니다. AuthToken을 참고하세요.
  • 인터넷에서 접근할 수 있고 JSON 본문이 담긴 POST 요청을 받는 HTTP 또는 HTTPS 엔드포인트.
  • 내 계정의 대시보드입니다. 팀 대시보드에서 작업하는 동안에는 웹훅 메뉴 항목이 표시되지 않습니다.

웹훅 만들기 #

  1. 웹훅 열기 #

    대시보드 메뉴에서 웹훅을 엽니다.

  2. 알림 받을 대상 선택 #

    설정기능
    토큰 웹훅 사용그룹의 AuthToken이 연결되거나 연결 해제될 때, 즉 해당 기기의 Localtonet 클라이언트가 온라인이 되거나 오프라인이 될 때 요청을 보냅니다.
    터널 웹훅 사용그룹의 AuthToken에 속한 터널이 연결되거나 연결 해제될 때 요청을 보냅니다.
    연결 시 전송연결됨으로 바뀔 때 요청을 보냅니다.
    연결 해제 시 전송연결 해제됨으로 바뀔 때 요청을 보냅니다.
    AuthToken 그룹감시할 토큰 그룹입니다. 필수 항목입니다.
    웹훅 URLLocaltonet이 호출하는 주소입니다. 필수 항목입니다.

    웹훅 유형 두 가지 중 하나 이상, 알림 유형 두 가지 중 하나 이상을 켜세요.

  3. 생성 #

    생성을 선택합니다. 웹훅이 양식 아래의 목록에 나타납니다.

웹훅 목록 #

각 행에는 토큰 웹훅, 터널 웹훅, 그룹 이름, URL, 연결 알림, 연결 해제 알림이 표시되며, 각 스위치는 활성 또는 비활성으로 나타납니다. 작업 열의 삭제 버튼은 확인 후 웹훅을 삭제합니다.

웹훅은 편집할 수 없습니다. URL, 그룹, 스위치를 바꾸려면 웹훅을 삭제하고 새로 만드세요. 같은 그룹에 웹훅을 여러 개 만들 수 있습니다. 예를 들어 연결에는 한 URL을, 연결 해제에는 다른 URL을 사용할 수 있습니다.

Localtonet이 보내는 요청 #

항목값
메서드POST
콘텐츠 유형application/json; charset=utf-8
본문아래 네 개의 필드가 있는 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"
}

전달 #

  • 실패한 호출은 다시 시도하지 않으므로 엔드포인트는 항상 사용 가능해야 하며 빠르게 응답해야 합니다.
  • 요청에는 서명이나 시크릿 헤더가 없습니다. 호출이 내 웹훅에서 온 것인지 확인하려면 URL에 길고 무작위인 값을 넣고(예: 경로 세그먼트나 쿼리 매개변수), 수신기에서 그 값을 확인하세요.
  • 연결 해제는 Localtonet이 클라이언트가 사라진 것을 확인한 시점에 보고되며, 기기의 연결이 끊긴 순간보다 조금 늦을 수 있습니다.
  • ActionDate는 표준 ISO 8601 파서로 해석하고, 값에 포함된 오프셋을 사용하세요. 고정된 시간대를 가정하지 마세요.

수신기 예시 #

어떤 웹 프레임워크든 사용할 수 있습니다. 수신기는 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);

이 수신기를 사용하면 웹훅 URL은 https://<YOUR_HOST>/localtonet/<YOUR_SECRET>입니다.

웹훅 테스트 #

  1. 테스트 기기의 AuthToken 하나를 웹훅의 토큰 그룹에 넣습니다.
  2. 해당 기기에서 토큰으로 Localtonet 클라이언트를 시작합니다. 연결 시 전송이 켜져 있으면 엔드포인트가 Type Token, Status Connected를 받습니다.
  3. Ctrl + C로 클라이언트를 중지합니다. 엔드포인트가 Status Disconnected를 받습니다.
  4. 터널 웹훅 사용이 켜져 있으면 내 터널에서 해당 토큰의 터널을 시작하고 중지하여 터널 이벤트를 받아 보세요.

아직 공개 엔드포인트가 없나요? 수신기를 내 컴퓨터에서 실행하고, 감시 중인 토큰과 다른 AuthToken의 Localtonet HTTP 터널로 공개하세요. 그러면 터널의 요청 검사기에 모든 웹훅 호출이 표시됩니다. 로그 및 검사를 참고하세요.

문제 해결 #

"웹훅 유형을 하나 이상 켜세요." 또는 "알림 유형을 하나 이상 켜세요."

생성을 선택하기 전에 토큰 웹훅 사용 또는 터널 웹훅 사용, 그리고 연결 시 전송 또는 연결 해제 시 전송을 켜세요.

"그룹은 필수입니다!"

AuthToken 그룹에서 토큰 그룹을 선택하세요. 목록이 비어 있으면 내 토큰에서 그룹을 만들고 토큰을 추가하세요.

요청이 도착하지 않습니다

기기의 AuthToken이 웹훅이 감시하는 그룹의 구성원인지, 목록에서 해당 스위치가 활성으로 표시되는지, 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"}'
토큰 이벤트는 오는데 터널 이벤트는 오지 않습니다

웹훅의 터널 웹훅이 활성이어야 하며, 터널이 그룹에 속한 AuthToken에 속해 있어야 합니다.

이 페이지에 도움이 필요하신가요? 커뮤니티에 질문하거나 지원 티켓을 만들어 주세요.

지원