웹훅이란? 앱끼리 서로 알리는 방법

웹훅은 무언가 일어나는 순간 한 서비스가 여러분의 앱에 보내는 자동 메시지입니다. 고객의 결제가 성공하면 Stripe는 앱 안의 주소로 "결제 성공, 세부 정보는 다음과 같습니다"라는 웹훅을 보내고, 앱은 이에 반응합니다. 주문을 결제 완료로 표시하고, 영수증을 보내고, 계정을 활성화합니다. 간단히 말해, API는 앱이 다른 서비스에 질문하는 것이고, 웹훅은 다른 서비스가 앱을 호출해서 무언가를 알려 주는 것입니다.

AI로 만들 때 웹훅이 중요한 이유

앱이 결제를 받거나, 다른 도구에서 양식 제출을 받거나, GitHub, Shopify, 캘린더 같은 서비스에 연결하는 순간 웹훅을 만나게 됩니다. 보통 무언가 일어났다는 것을 아는 올바른 방법이 웹훅이지만, AI로 만든 앱이 미묘하게 잘못되기 쉬운 곳이기도 합니다.

• 엔드포인트가 모든 요청을 받아들여서, 누구든 "결제 성공" 이벤트를 위조할 수 있습니다.
• 앱이 웹훅이 아니라 결제 완료 후 리디렉션되는 페이지에서 접근 권한을 부여합니다. 그러면 탭을 일찍 닫은 사람은 결제한 것을 받지 못하고, 성공 URL을 알아낸 사람은 공짜로 받게 됩니다.
• 같은 이벤트가 두 번 도착해서 고객이 주문이나 이메일을 두 번 받습니다.

웹훅이 어떻게 작동하는지 알면, 처음부터 이런 보호 장치를 요청할 수 있습니다.

일상적인 비유: 배송 문자

택배가 도착했는지 확인하는 방법은 두 가지입니다. 10분마다 현관까지 걸어가서 확인할 수 있습니다. 이것이 폴링입니다. 앱이 API를 반복해서 호출하며 "새로운 것 있나요?"라고 묻는 것이죠. 아니면 택배 기사가 배달이 끝나면 문자를 보내 줄 수도 있습니다. 이것이 웹훅입니다.

그 문자가 훨씬 낫다는 것은 분명하지만, 그 문자를 믿을 수 있을 때만 그렇습니다. 누구든 "택배 배달 완료" 메시지를 보낼 수 있다면, 그것이 정말 택배 기사에게서 왔는지 확인할 방법이 필요합니다. 또 문자가 왔을 때 휴대폰이 꺼져 있었다면, 택배 기사가 나중에 다시 시도하기를 바랄 것입니다. 이 두 가지 문제, 즉 검증과 재시도가 웹훅을 까다롭게 만드는 대부분입니다.

웹훅이 작동하는 방식, 단계별로

1. 엔드포인트를 만듭니다. 앱의 백엔드에 POST 요청을 받는 https://yourapp.com/webhooks/stripe 같은 URL을 만듭니다.
2. 제공업체에 이 URL을 등록하고 받고 싶은 이벤트를 고릅니다(예: "결제 세션 완료", "구독 취소").
3. 제공업체가 서명 비밀 키를 줍니다. 이것을 서버에 시크릿으로 저장하세요. 환경 변수와 시크릿을 참고하세요.
4. 이벤트가 발생합니다. 제공업체가 이벤트를 설명하는 JSON 본문과 서명 헤더를 담아 여러분의 URL로 HTTP 요청을 보냅니다.
5. 앱이 서명을 검증하고, 이벤트 ID를 기록한 뒤, 성공 코드(200)를 빠르게 응답하고, 그다음에 작업을 처리합니다.
6. 앱이 성공으로 응답하지 않으면, 많은 제공업체가 나중에 다시 시도합니다.

서명

서명은 요청이 제공업체에서 왔고 변조되지 않았다는 것을 증명합니다. 예를 들어 Stripe는 서명 비밀 키를 사용해 요청 본문과 타임스탬프에 대해 SHA-256 기반의 HMAC(일종의 키가 있는 지문)을 계산하고, 이를 Stripe-Signature 헤더로 보냅니다. 앱은 자기가 가진 비밀 키 사본으로 같은 계산을 하고, 결과가 일치하면 요청이 진짜라고 판단합니다. 타임스탬프도 서명되므로, 누군가 기록해 두었다가 나중에 재전송한 오래된 요청을 거부할 수 있습니다. Stripe의 라이브러리는 2026년 9월 기준 문서에 따르면 기본적으로 5분의 허용 시간을 둡니다.

실무에서 중요한 세부 사항은 서명이 원본 요청 본문에 대해 계산된다는 점입니다. 검증 전에 프레임워크가 JSON을 파싱하고 다시 포맷하면 검사가 실패합니다. 이것은 아주 흔한 버그입니다.

재시도, 중복, 순서

제공업체마다 다르므로 각 문서를 확인하세요. 2026년 9월 기준은 다음과 같습니다.

Stripe 문서는 또한 이벤트가 발생한 순서대로 도착한다는 보장이 없고, 같은 이벤트가 드물게 두 번 이상 도착할 수 있다고 설명하며, 따라서 이벤트 ID를 추적할 것을 권장합니다.

어느 제공업체에나 적용되는 일반적인 교훈은 이렇습니다. 이벤트는 늦게, 두 번 이상, 그리고 순서가 뒤바뀌어 도착할 수 있습니다. 핸들러는 멱등성이 있어야 합니다. 즉 같은 이벤트를 두 번 처리해도 한 번 처리한 것과 결과가 같아야 합니다.

실제 예: 유료 강좌 열어 주기

온라인 강좌를 판매한다고 해 봅시다. 수강생이 구매를 클릭하고, Stripe가 호스팅하는 결제 페이지에서 결제한 뒤 여러분의 사이트로 돌아옵니다.

취약한 방법: "감사합니다" 페이지가 강좌를 열어 줍니다. 수강생이 리디렉션 중에 브라우저를 닫으면, 결제는 했지만 접근 권한은 없습니다. 감사 페이지 URL을 누군가 추측하면, 결제하지 않고도 접근 권한을 얻습니다.

웹훅 방법:

1. Stripe가 결제를 확인하면 checkout.session.completed 이벤트를 /webhooks/stripe로 보냅니다.
2. 백엔드가 서명 비밀 키로 서명을 검증합니다. 실패하면 400으로 응답하고 아무것도 하지 않습니다.
3. 그 이벤트 ID가 이미 처리되었는지 확인합니다. 그렇다면 200으로 응답하고 멈춥니다.
4. 이벤트 ID를 저장하고 200으로 응답한 뒤, 수강생에게 접근 권한을 주고 환영 이메일을 보냅니다.
5. 감사 페이지는 "결제가 완료되었습니다. 강좌가 곧 나타납니다"라고만 말하고, 수강생의 접근 상태를 확인합니다.

나중에 구독이 취소되거나 카드 결제가 실패하면, 다른 웹훅 이벤트가 앱에 알려서 접근 권한을 제거하거나 일시 중지하게 합니다. 이렇게 해서 구독 상품은 청구와 계속 동기화됩니다. SaaS란 무엇인가와 앱에 결제를 추가하는 방법을 참고하세요.

핵심 용어

• 엔드포인트: 웹훅을 받는, 앱 안의 URL입니다.
• 이벤트 / 페이로드: 무슨 일이 일어났는지와 그것을 설명하는 데이터입니다(보통 JSON).
• 서명 비밀 키: 서명을 검증하는 데 쓰는 공유 비밀 키입니다.
• 멱등성(Idempotent): 같은 결과로 여러 번 실행해도 안전한 성질입니다.
• 폴링: 웹훅을 기다리는 대신 변경 사항을 찾으려고 API를 반복해서 호출하는 것입니다.
• 터널: 개발 중에 웹훅이 노트북에 닿도록 임시 공개 URL을 주는 도구입니다.

흔한 실수와 오해

• 서명을 검증하지 않음. 엔드포인트 URL은 비밀이 아닙니다. 검증이 있어야 요청을 신뢰할 수 있습니다.
• 응답하기 전에 느린 작업을 함. 응답 전에 이메일을 보내거나 PDF를 생성하면 타임아웃이 나고, 타임아웃은 재시도를 일으키며, 재시도는 중복을 만듭니다.
• 정확히 한 번, 순서대로 도착한다고 가정함. 이벤트 ID를 기록하고, 도착 순서에 의존하지 마세요.
• 미리보기 URL 사용. 웹훅에는 안정적인 공개 주소가 필요합니다. 비공개 미리보기와 localhost는 인터넷에서 접근할 수 없으니, 게시한 URL을 사용하거나 테스트 중에는 터널을 쓰세요.
• 테스트 시크릿과 라이브 시크릿을 섞음. 제공업체는 테스트 모드와 라이브 모드에 서로 다른 서명 비밀 키를 발급하는 경우가 많습니다. 둘 다 저장하고 맞는 것을 쓰세요.
• 중요한 결정을 페이로드만 믿고 내림. 고위험 동작이라면, 이벤트를 받은 뒤 제공업체의 API에서 최신 상태를 가져오는 것이 합리적입니다.

AI 빌더에게 무엇을 요청할까요

서버에 POST /webhooks/stripe 엔드포인트를 추가해 줘. 원본 요청 본문과 STRIPE_WEBHOOK_SECRET 비밀 키를 사용해 Stripe 서명을 검증하고, 유효하지 않은 서명은 400으로 거부해 줘. 각 이벤트 ID를 저장하고 이미 처리된 이벤트는 건너뛰어 줘. 빠르게 200으로 응답한 뒤, checkout.session.completed는 주문을 결제 완료로 표시하고 영수증을 보내는 방식으로 처리해 줘. 이벤트 유형을 기록해 줘. 결제 성공 페이지에서는 접근 권한을 주지 마.

그다음 테스트하세요. 제공업체의 대시보드에서 테스트 이벤트를 보내고, 같은 것을 다시 보내고, 잘못된 서명을 가진 요청도 보내 보세요. 첫 번째만 무언가를 바꿔야 합니다.

Mythex의 웹훅

Mythex는 별도의 웹훅 서비스를 운영하지 않습니다. 에이전트에게 앱 자체 백엔드에 웹훅 엔드포인트를 추가하도록 요청하고, 웹훅에는 공개 주소가 필요하므로 제공업체가 게시된 URL을 가리키도록 설정하세요. 서명 비밀 키는 프로젝트 시크릿에 넣고, 라이브 앱에서 이를 바꾸면 다시 게시하세요. 웹훅 처리 문서 레시피에 시작 프롬프트가 있고, 결제를 받는 앱의 출발점으로는 스토어 템플릿이 좋습니다.

자주 묻는 질문