전체 글 목록
Chae-won Chae-won · 2026년 9월 16일

웹훅, 폴링, 그리고 태스크 — AI에게 일을 맡기는 세 번째 방법

웹훅, 폴링, 그리고 태스크 — AI에게 일을 맡기는 세 번째 방법

안녕하세요, 채원이에요.

지난 글에서 웹훅과 폴링을 택배에 비유했죠. 폴링은 "택배 왔어요?" 하고 계속 전화하는 것, 웹훅은 택배가 오면 초인종을 눌러 주는 것이었어요.

요즘은 ChatGPT나 Claude 같은 AI 안에서 일을 처리하는 분이 많아졌어요. 자료를 찾고, 글을 쓰고, 이제는 대화하면서 내 시스템에 일을 시키기도 하죠. 그러다 보니 이런 요청을 받게 됐어요. "AI에게 일을 시키고, 결과를 받으려면 어떻게 해야 하나요?"

오늘은 이 요청에 웹훅도 폴링도 딱 맞지 않았던 이유, 그리고 그래서 새로 만든 태스크 이야기를 해 볼게요.

지금까지는 직접 엮어야 했어요

태스크가 없을 때도 방법은 있었어요. 엔드포인트 두 개를 AI와 내 시스템을 이어 주는 통로로 쓰는 거예요. 흐름은 이래요.

  1. AI가 "요청" 엔드포인트에 할 일을 적는다
  2. 내 서버가 웹훅으로 받거나, 폴링으로 계속 확인한다
  3. 내 서버가 일을 끝내고 "결과" 엔드포인트에 적는다
  4. AI가 결과 엔드포인트를 조회해서 사용자에게 알려 준다

우체통 두 개로 주고받는 교환 일기 같은 방식이에요. 잘 돌아가긴 하는데, 쓰다 보면 불편한 곳이 세 군데 생겨요.

AI 대화는 기다려 주지 않아요

보고서 만들기, 대량 변환, ERP에 발주 넣기 같은 일은 몇 분에서 몇 시간이 걸려요. 그런데 AI의 답장은 그렇게 오래 기다려 주지 않아요.

그렇다고 AI가 "10분 뒤에 다시 확인할게요" 하고 알람을 맞춰 둘 수도 없어요. AI는 여러분이 말을 걸 때만 움직이거든요. 결과는 결국 다음에 말을 걸었을 때 확인하게 돼요.

그래서 필요한 건 "일을 맡기고, 나중에 물어보면 결과를 알려 주는" 구조예요. 택배로 치면 송장 번호가 필요한 거죠.

웹훅이 안 맞는 이유: 초인종을 달 곳이 없어요

웹훅은 "도착하면 알려 줄게"예요. 그러려면 알림을 받을 주소가 있어야 해요.

그런데 AI 대화에는 초인종을 달 문이 없어요. 대화창은 주소가 있는 서버가 아니니까요. 결과가 도착했다고 대화 속 AI를 깨울 방법이 없어요.

보안 문제도 있었어요. 웹훅을 AI 대화로 설정하면 인증 헤더 같은 비밀값을 대화에 입력하게 돼요. 대화 기록은 생각보다 여러 곳에 남아요. 그래서 이번 업데이트부터 웹훅 인증 헤더는 대시보드에서만 설정하도록 바꿨어요. 이미 저장해 둔 헤더는 그대로 전송돼요.

폴링이 비싼 이유: 빈 전화가 대부분이에요

폴링은 AI 대화와 잘 맞아요. 궁금할 때 물어보면 되니까요. 문제는 일을 받는 쪽이에요.

위의 교환 일기 방식에서 여러분의 서버는 "새 요청 있어요?"를 계속 물어봐야 해요. 요청이 하루 몇 건뿐이어도요. 1분마다 확인하면 한 달에 43,200번이고, 대부분은 "없어요"라는 대답이에요. 그리고 그 한 번 한 번이 월 호출 한도에서 빠져요.

그래서 태스크를 만들었어요

태스크는 이 교환 일기를 택배 접수 창구로 바꾼 거예요.

  1. 워커를 한 번 등록해요 — 대시보드에서 일을 받을 곳(워커)의 이름, 설명, 주소를 등록해요
  2. AI가 일을 맡겨요 — "우리 ERP에 A-1042 30개 발주 넣어줘"라고 하면, AI가 태스크를 만들고 송장 번호(태스크 ID)를 받아요
  3. 3Min API가 워커에 배달해요 — 서명을 붙여 워커 주소로 보내고, 실패하면 알아서 다시 보내요
  4. 워커가 일을 하고 결과를 회신해요 — 오래 걸려도 괜찮아요. 최대 24시간까지 기다려요
  5. AI가 결과를 확인해요 — 다음에 "아까 그거 어떻게 됐어?" 하고 물으면 결과를 알려 줘요

AI는 워커의 이름과 설명만 보고 어디로 일을 보낼지 골라요. 워커 주소나 인증값, 서명 시크릿은 대시보드에만 있고, 대화에는 한 번도 나오지 않아요.

태스크는 누가 만드나요?

여기까지 읽으면 이런 생각이 드실 거예요. "세상에 할 일이 얼마나 많은데, 그걸 3Min API가 다 준비해 둔 건가?"

아니에요. 3Min API는 일을 직접 하지 않아요. 맡긴 일을 워커에 배달하고, 지금 어떤 상태인지 기록해 둘 뿐이에요. 택배사가 물건을 만들지 않는 것과 같아요.

  • 워커 — 일을 하는 곳이에요. 여러분의 서버나 프로그램이고, 어떤 일을 할지는 워커가 정해요
  • 태스크 — 워커에 맡긴 일 한 건이에요. 기능 목록이 아니라 송장 한 장이라고 생각하시면 돼요

그러니까 "발주 넣기" 워커를 등록하면 AI는 발주를 맡길 수 있고, "보고서 만들기" 워커를 등록하면 보고서를 맡길 수 있어요. 할 수 있는 일의 범위는 여러분이 연결한 워커만큼이에요.

처음부터 만들 필요는 없어요

"그럼 결국 서버를 새로 만들어야 하나요?" 꼭 그렇지는 않아요. 워커가 할 일은 딱 두 가지거든요.

  1. 3Min API가 보낸 요청을 받는다
  2. 일이 끝나면 결과를 3Min API에 보낸다

HTTP 요청을 받고 보낼 수 있으면 무엇이든 워커가 될 수 있어요. 그래서 이미 있는 것에 붙이는 방법이 여러 가지예요.

  • 이미 쓰고 있는 스크립트나 프로그램 — 요청을 받아 그 프로그램을 실행하고, 결과만 돌려주는 얇은 껍데기를 씌우면 돼요
  • 요청을 받고 보낼 수 있는 자동화 도구 — 받는 단계와 보내는 단계를 이어 주면 코드 없이도 워커를 꾸릴 수 있어요
  • 내 PC에서만 돌아가는 작업 — 로컬 워커로 만들면 돼요. 3Min API CLI가 내 PC에서 실행해 주니까 공개 주소가 필요 없어요(아래에서 설명할게요)
  • 껍데기 코드는 AI에게 부탁 — "3minapi 태스크 워커 만들어줘"라고 하면, AI가 3Min API의 안내 문서를 읽고 코드를 써 줘요

내 PC에서 돌아가는 작업이라면: 로컬 워커

퍼블릭 워커에 일을 배달하려면, 3Min API가 인터넷에서 찾아갈 수 있는 주소로 워커에 닿아야 해요. 그런데 집이나 사무실 PC는 공유기 안쪽에 있어서, 바깥에서는 닿을 수가 없어요. 로컬 워커는 방향을 거꾸로 바꿔요. 내 PC에서 3Min API CLI가 실행되면서 기다리는 일을 3Min API에서 직접 가져오거든요. 그래서 공개 주소도, 공유기 설정도, 열린 포트도 필요 없어요.

로컬 워커는 그냥 파일 속 함수 하나예요. 파일 하나가 워커 하나죠. npm install -g @3minapi/cli로 CLI를 설치하고, 3minapi worker new로 워커를 만든 다음, 3minapi start를 실행하면 돼요. PC가 꺼져 있는 동안 일은 기다려 주지만, 24시간 안에 가져가지 않으면 실패로 처리돼요. 자세한 내용은 로컬 워커(CLI) 가이드에 있어요.

한 가지 주의할 점이 있어요. 이미 있는 사내 API 주소를 워커 주소로 그대로 넣으면 동작하지 않아요. 3Min API가 보내는 요청 형식이 정해져 있고, 일이 끝나면 결과를 되돌려 보내야 하거든요. 그래서 기존 시스템과 3Min API 사이에 위의 얇은 껍데기가 하나 필요해요.

태스크도 결국 HTTP 요청이에요

태스크라고 해서 특별한 통신 방식이 있는 건 아니에요. 지난 글에서 이야기한 웹훅, API 호출과 같은 요청이 순서대로 오갈 뿐이에요.

순서 누가 → 누구에게 하는 일 호출 수
— AI → 3Min API 워커 목록 확인 (필요할 때) 1
① AI → 3Min API 일 맡기기 1
② 3Min API → 워커 배달 (실패하면 재시도) 세지 않음
③ 워커 → 3Min API 결과 회신 (진행 상황도 보낼 수 있음) 1 (보낼 때마다)
④ AI → 3Min API 결과 확인 1~2

②번이 핵심이에요. 배달은 웹훅이 하던 일을 3Min API가 대신하는 거예요. 엔드포인트의 웹훅이 "밖에서 들어온 데이터를 여러분에게 보내는 것"이라면, 태스크의 배달은 "AI가 맡긴 일을 여러분의 워커에 보내는 것"이에요. 웹훅과 같은 서명 방식을 쓰고, 배달과 재시도는 호출 수에 넣지 않아요.

그래서 워커는 "새 요청 있어요?"를 물어볼 필요가 없어요. 일이 생기면 알아서 도착하니까요. 진행 상황을 따로 보내지 않으면, 워커 목록 확인까지 합쳐도 태스크 한 건은 3~5번이면 끝나요. 1분마다 확인하느라 한 달에 43,200번을 쓰던 것과 비교해 보세요.

엔드포인트와 태스크, 언제 뭘 쓰나요?

  • 데이터를 받아서 쌓고 모으는 게 목적이면 → 엔드포인트 (웹훅·폴링)
  • AI가 내 시스템에 일을 시키고 결과를 받는 게 목적이면 → 태스크

둘은 서로를 대신하지 않아요. 워커가 처리한 결과를 다시 엔드포인트에 쌓으면, 받은 데이터를 가공해서 모아 두는 일까지 AI에게 맡길 수 있어요. 같이 쓸 때 가장 강해요.

정리

  • 웹훅은 받을 주소가 있어야 하고, AI 대화에는 그 주소가 없어요
  • 폴링은 AI 대화와는 맞지만, 일을 받는 쪽이 빈 확인에 호출을 써요
  • 태스크는 맡기고 → 배달하고 → 나중에 확인하는 구조예요. 3Min API는 배달과 기록을 맡고, 일은 여러분이 연결한 워커가 해요
  • 워커는 새로 만들지 않아도 돼요. 요청을 받고 보낼 수 있는 것이면 이미 있는 것에 붙일 수 있어요

작업 기한은 최대 24시간이에요. 워커 등록 방법, 요청 형식, 플랜별 제한은 태스크 가이드에 정리해 두었어요. 대시보드의 태스크 메뉴에서 바로 시작할 수 있어요.