RSS

DUOLABS AI 기능 탐구 10: 외부 이벤트로 AI 작업을 실행하는 통합·웹훅

AI 자동화글: , Duolabs8분 읽기blogduolabs-aiduolabs-ai-seriesintegration-automationmodel-openai-gpt-5.5technical-notewebhooks

DUOLABS AI 기능 탐구 열 번째 글은 외부 시스템의 이벤트를 받아 구조화 추출이나 에이전트를 실행하는 통합·웹훅입니다.

AI 기능을 화면에서 직접 실행하는 것만으로는 업무 자동화가 완성되지 않습니다. 문의가 접수되거나 폼이 제출되는 순간, 다른 시스템이 AI 작업을 호출하고 결과를 받아 다음 단계로 넘길 수 있어야 합니다. 웹훅은 이 연결을 만드는 간단한 방법입니다.

기능 직접 보기: DUOLABS AI 통합·웹훅

이 화면은 공개 공유 데모입니다. 실제 서비스의 웹훅 주소, 인증 토큰, 고객 데이터나 내부 에이전트를 등록하지 마세요. 생성된 데모 웹훅도 다른 방문자가 보거나 비활성화·삭제할 수 있다고 가정해야 합니다.

웹훅은 외부 이벤트를 받는 입구입니다

웹훅은 특정 주소로 HTTP 요청을 보내 작업을 시작하는 방식입니다.

홈페이지 상담 폼 제출
→ 웹훅으로 문의 내용 전송
→ AI가 회사명·담당자·요청 사항 추출
→ 구조화된 JSON 반환
→ CRM 등록 또는 담당자 검토

일정하게 서버를 조회하는 폴링과 달리, 이벤트가 발생한 시스템이 즉시 요청을 보냅니다. 자동화 플랫폼, 쇼핑몰, 고객지원 도구와 자체 업무 시스템에서 널리 사용할 수 있는 패턴입니다.

DUOLABS AI의 웹훅은 외부에서 들어오는 POST 요청의 text 값을 받아 등록된 AI 작업을 실행합니다.

두 종류의 실행 대상을 연결할 수 있습니다

구조화 추출 웹훅

영업 리드, 영수증 항목, 이력서 경력처럼 미리 정한 스키마에 맞춰 텍스트를 구조화합니다.

{
  "text": "세모상사 김가상 팀장이 다음 주 웹사이트 상담을 요청했습니다."
}

응답에는 추출된 행과 처리 시간이 포함됩니다. 외부 시스템은 결과를 검증한 뒤 CRM이나 데이터베이스에 저장할 수 있습니다.

공개 데모의 추출 웹훅은 비용과 남용을 제한하기 위해 준비된 로컬 실행 설정만 사용합니다. 실제 구축에서는 데이터 정책, 처리량과 품질 기준에 맞는 모델을 선택해야 합니다.

에이전트 웹훅

앞서 만든 에이전트를 실행 대상으로 선택할 수 있습니다. 요청의 text가 에이전트의 사용자 메시지가 되고, 저장된 시스템 프롬프트와 허용 도구를 사용해 답변을 만듭니다.

에이전트가 삭제되면 해당 에이전트를 가리키던 웹훅은 정상 실행할 수 없습니다. 설정의 의존 관계를 관리하고 삭제 전에 연결된 자동화를 확인해야 합니다.

DUOLABS AI에서는 어떻게 만드나요?

1. 웹훅 이름과 실행 대상을 선택합니다

“신규 문의 구조화”, “배송 상태 안내 에이전트”처럼 이벤트와 목적이 드러나는 이름이 좋습니다.

실행 대상은 추출 스키마 또는 에이전트 중 하나를 선택합니다. 추출은 결과 구조와 실행 설정을 고르고, 에이전트는 기존 에이전트 목록에서 대상을 선택합니다.

2. 고유한 호출 주소를 확인합니다

웹훅을 만들면 고유 토큰이 포함된 POST 주소와 cURL 예시가 제공됩니다.

curl -X POST https://example.com/api/hooks/WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"text":"처리할 테스트 문장"}'

실제 토큰은 비밀번호처럼 다뤄야 합니다. URL을 문서, 채팅, 소스 코드나 공개 로그에 남기면 다른 사람이 작업을 호출할 수 있습니다. 이 글의 예시는 실제 주소가 아닌 형식만 보여 줍니다.

3. 샘플로 테스트 발사합니다

상세 화면에서 가상 텍스트를 보내고 응답을 확인할 수 있습니다. 추출 웹훅은 구조화된 행을, 에이전트 웹훅은 생성된 답변을 보여 줍니다.

공개 데모의 웹훅 호출은 분당 최대 6회, 입력은 8,000자 이하로 제한됩니다. 운영 환경의 제한은 모델 처리량, 예상 트래픽과 비용에 맞춰 별도로 설계해야 합니다.

4. 활성 상태와 실행 이력을 확인합니다

웹훅별 호출 횟수와 마지막 호출 시각을 볼 수 있고, 필요하면 활성·비활성 상태를 바꿀 수 있습니다. 비활성화된 주소는 작업을 실행하지 않습니다.

최근 트리거 영역에는 성공·실패, 사용 모델, 처리 시간과 실행 시각이 표시됩니다. 오류를 발견하고 처리량을 파악하는 기본 관측 지점입니다.

어떤 업무 흐름에 연결할 수 있을까요?

상담 폼과 CRM

홈페이지 문의를 구조화하고 담당 부서를 정한 뒤 CRM 등록 후보를 만들 수 있습니다. 공개 폼에는 스팸과 악성 입력이 들어올 수 있으므로 검증과 속도 제한이 필요합니다.

이메일 자동화

수신 메일의 본문을 웹훅으로 보내 문의 유형, 회사명과 요청 내용을 추출할 수 있습니다. 첨부파일과 HTML 정리는 별도 전처리가 필요합니다.

고객지원 티켓

새 티켓 이벤트로 에이전트를 실행해 답변 초안이나 필요한 조회 항목을 만들 수 있습니다. 고객에게 바로 전송하기보다 상담원이 검토하는 단계부터 시작하는 편이 안전합니다.

문서 처리 파이프라인

OCR이 끝난 텍스트를 웹훅으로 보내 정해진 스키마로 구조화하고 검수 큐에 넣을 수 있습니다. 원본 문서의 식별자와 추출 결과를 연결하되 민감정보를 로그에 그대로 남기지 않아야 합니다.

토큰 하나만으로 충분한 인증일까요?

고유한 URL 토큰은 간단하지만 운영 보안을 전부 해결하지는 않습니다. 실서비스에는 다음 장치를 검토해야 합니다.

  • 요청 본문과 시각을 서명하는 HMAC 검증
  • 토큰의 안전한 보관과 정기적인 교체
  • 허용된 발신 시스템이나 네트워크 제한
  • 요청 크기와 호출 빈도 제한
  • 오래된 요청과 재전송 공격 차단
  • 이벤트 ID를 이용한 중복 실행 방지
  • 실행 결과와 오류의 감사 로그

특히 URL은 브라우저 기록, 프록시와 서버 로그에 남을 수 있습니다. 토큰이 노출되었다고 판단되면 기존 웹훅을 비활성화하거나 삭제하고 새 주소를 발급해야 합니다.

중복 이벤트와 실패를 고려해야 합니다

외부 시스템은 응답을 받지 못하면 같은 이벤트를 다시 보낼 수 있습니다. AI 작업이 성공했지만 네트워크 응답만 끊어진 경우도 있습니다.

주문 취소, 메시지 발송이나 데이터 생성처럼 상태를 바꾸는 후속 작업은 같은 이벤트가 두 번 와도 한 번만 처리되어야 합니다. 이벤트 ID와 처리 상태를 저장하는 멱등성 설계가 필요합니다.

실패도 구분해야 합니다.

  • 잘못된 JSON이나 빈 입력
  • 비활성화되거나 존재하지 않는 웹훅
  • 호출 제한 초과
  • 모델 또는 연결 도구 오류
  • 결과 검증 실패
  • 후속 시스템 저장 실패

오류 유형에 따라 재시도, 보류, 폐기 또는 사람 검토로 보내야 합니다.

공개 샘플로 직접 확인해 보기

DUOLABS AI 통합·웹훅에서 이미 준비된 공개 샘플의 호출 횟수와 최근 트리거를 살펴보세요. 직접 시험할 때는 가상의 짧은 문장만 사용하고, 화면에 표시된 토큰과 주소를 외부에 공유하지 마세요.

실서비스에서는 웹훅을 만들 수 있는 사람, 주소를 볼 수 있는 사람, 실행 기록을 조회할 수 있는 사람을 분리해야 합니다. AI 파이프라인 연결은 편리하지만 입력 검증, 인증, 중복 방지와 관측이 함께 있어야 안정적인 자동화가 됩니다.

이전 글: DUOLABS AI 기능 탐구 9: 변수와 버전으로 프롬프트를 관리하는 라이브러리

다음 글: DUOLABS AI 기능 탐구 11: 같은 프롬프트로 여러 모델을 비교하는 플레이그라운드

함께 읽기