Make Webhook

Make Webhook

웹훅(webhook)은 어떤 앱에서 이벤트가 생겼을 때, 그 사실을 다른 쪽에 알려주는 통로예요. Make에서 시나리오를 만들다 보면 "특정 서비스에서 데이터가 들어왔을 때 바로 처리하고 싶다"는 상황이 자주 생기는데, 이때가 바로 Webhooks 앱이 필요한 순간이에요. 이 모듈은 시나리오가 주기적으로 서비스를 물어보는(polling) 방식이 아니라, 외부 서비스가 우리에게 데이터를 보내 오면 그 즉시 시나리오를 실행하게 해요. 그래서 웹훅은 보통 즉시 트리거(instant trigger) 역할을 하죠.

Make의 Webhooks 앱 하나로 세 가지를 만들 수 있어요. **커스텀 웹훅(Custom webhook)**은 어떤 데이터든 받을 수 있는 고유 URL을 만들어 주고, **커스텀 메일훅(Custom mailhook)**은 이메일을 받으면 트리거 되고, **웹훅 응답(Webhook response)**은 호출한 쪽에 어떤 응답을 돌려줄지 정해요. 이 문서에서는 이 세 가지를 차례로 다뤄볼게요.

출처: 문서

본문

커스텀 웹훅 만들기

커스텀 웹훅 모듈로 어떤 서드파티 서비스에서든 시나리오를 즉시 트리거 할 수 있어요. 이 모듈이 고유한 웹훅 URL을 만들어 주면, 서비스들이 그 URL을 호출해서 Make에 데이터를 보내는 구조예요.

:::hint{type="info"} 각 시나리오는 자기만의 웹훅을 사용해요. 같은 웹훅을 여러 시나리오에서 쓸 수는 없어요. :::

커스텀 웹훅 모듈로 새 웹훅을 만드는 순서는 이렇게 돼요.

  1. 시나리오 빌더에서 앱 검색에 Webhooks > Custom webhook 모듈을 찾아요.

  2. Webhook 드롭다운 옆의 Add 를 클릭해요.

  3. Webhook name 에 웹훅의 고유한 이름을 넣어요.

  4. (선택) API Key Authentication 에서 API 키를 하나 이상 추가할 수 있어요.

    • + Add API Key 를 클릭해요.
    • Create a keychain 을 클릭해요.
    • Name 에 새 키체인(keychain)의 고유한 이름을 넣어요.
    • API Key Value 에 키값을 입력해요. ASCII 문자만 들어가야 하고, 512자 이하여야 해요. 보안 때문에 나중에는 이 값을 다시 볼 수 없으니 안전한 곳에 따로 보관해 두세요.
    • Create 를 클릭해요.
    • 필요하다면 API 키를 더 추가해요.

  5. 요청에는 API 키를 x-make-apikey 헤더에 포함해서 보내요.

  6. Save 를 클릭해요.

이제 커스텀 웹훅 모듈용 웹훅이 하나 추가됐어요. Make가 URL을 생성하고 요청을 기다리기 시작해요.

웹훅 데이터 구조 정의 (선택)

들어오는 웹훅 요청에 **데이터 구조(data structure)**를 정의해 두는 걸 권장해요. 데이터 구조는 웹훅을 호출하는 서드파티 서비스가 보낼 값이 어떤 형태인지 알려줘요. 데이터 구조가 없으면 Make가 들어오는 모든 데이터를 검증 없이 받아들이는데, 그러면 예상치 못한 데이터나 잘못된 데이터가 웹훅 단계에서 걸러지지 않아요. 그 뒤에 그 데이터에 의존하는 모듈에서 오류가 날 수 있어요.

웹훅 데이터 구조는 웹훅을 만들 때 정의하거나, 웹훅 URL을 호출해서 정의할 수 있어요.

방법 언제 쓰면 좋은지
웹훅 만들기 (Create a webhook) 웹훅을 만들 때 Advanced settings > Data structure 에서 새 데이터 구조를 추가하거나 기존 것을 선택해요. 데이터 값을 미리 알고 있을 때 들어오는 데이터를 검증하고 싶다면 이 방법을 써요.
웹훅 호출 (Call the webhook) 서드파티 서비스나 Postman에서 웹훅 URL로 샘플 데이터를 담은 테스트 요청을 보내요. 나중에 모듈들에서 매핑할 수 있는 데이터 값이 무엇인지 확인하고 싶을 때 써요.
웹훅 재호출 (Re-call the webhook) 커스텀 웹훅 모듈 설정에서 Detect new values 를 클릭하고, 새 샘플 데이터로 테스트 요청을 다시 보내요. 데이터 구조를 바꾸고 싶을 때 써요.

Call the webhook 또는 Re-call the webhook 방식을 쓰면 재사용 가능한 데이터 구조가 Data structures 섹션에 만들어지지는 않아요. 데이터 구조가 웹훅과 함께 내부적으로 저장될 뿐이고, 들어오는 데이터를 검증하지도 않아요.

지원되는 수신 데이터 형식

웹훅은 다음 수신 데이터 형식을 지원해요.

  • 쿼리 문자열 (query string)
  • 폼 데이터 (form data)
  • JSON

웹훅이 쿼리 문자열과 폼 데이터(또는 JSON)를 동시에 받으면, 시스템은 이 데이터를 하나의 번들로 합쳐요. 요청에 서로 다른 형식으로 중복된 데이터가 있다면 쿼리 문자열이 우선해서 다른 형식으로 받은 데이터를 덮어써요. 쿼리 문자열, 폼 데이터, JSON에 데이터를 중복해서 넣는 건 권장하지 않아요.

쿼리 문자열 (Query string)

GET https://hook.make.com/yourunique32characterslongstring?name=make&job=automate

폼 데이터 (Form data)

POST https://hook.make.com/yourunique32characterslongstring
Content-Type: application/x-www-form-urlencoded

name=integrobot&job=automate

multipart

POST https://hook.make.com/yourunique32characterslongstring
Content-Type: multipart/form-data; boundary=generatedboundary

--generatedboundary
Content-Disposition: form-data; name="file"; filename="file.txt"
Content-Type: text/plain

content of file.txt
--generatedboundary
Content-Disposition: form-data; name="name"

Make
--generatedboundary

multipart/form-data로 인코딩된 파일을 받으려면, name, mime, data라는 중첩 필드를 가진 컬렉션(collection) 타입 필드를 포함하는 데이터 구조를 설정해야 해요.

  • name : 텍스트 타입, 업로드된 파일의 이름을 담아요.
  • mime : 텍스트 타입, [mime] 형식의 파일 형식을 담아요. (참고: https://en.wikipedia.org/wiki/MIME)
  • data : 버퍼 타입, 전송되는 파일의 이진(binary) 데이터를 담아요.

JSON

POST https://hook.make.com/yourunique32characterslongstring
Content-Type: application/json

{"name": "integrobot", "job": "automate"}

원본 JSON 그대로에 접근하려면 웹훅 설정을 열고 JSON pass through 옵션을 켜면 돼요.

웹훅 페이로드의 최대 크기(Content-Length)는 구독 등급과 상관없이 5 MB (5,242,880 bytes) 예요.

웹훅 요청 헤더 사용 (선택)

들어오는 웹훅 요청의 헤더를 시나리오에서 쓰고 싶다면 요청 헤더를 활성화해요.

  1. Webhooks > Custom webhooks 모듈에서 Webhook 옆의 Edit 또는 Add 를 클릭해요.
  2. Advanced settings 를 토글해요.
  3. Get request headers 에서 Yes 를 선택해요.

그러면 요청 헤더가 활성화돼요. x-make-apikey는 예약어(reserved word)라서, 이걸 쓰면 값이 자동으로 삭제(sanitize)돼서 받지 못해요.

웹훅 설정 수정

웹훅을 만든 뒤에도 수정할 수 있어요. 단, team admin, team member, team restricted member 역할이 있어야 해요. 웹훅 설정을 수정하려면 왼쪽 사이드바의 Webhooks 로 가서, 웹훅 옆의 점 3개 메뉴를 클릭하고 Edit 을 선택한 뒤 필드를 바꾸고 저장하면 돼요.

커스텀 웹훅 모듈에서 볼 수 있는 웹훅 설정은 이 표와 같아요.

설정 설명
API Key Authentication 접근을 통제하는 선택적인 추가 보안 계층이에요. 예를 들어 API 키를 추가·제거·업데이트하면서 사용자 접근을 통제할 수 있어요.
IP Restrictions 쉼표로 구분된 허용 IP 주소 목록이에요. 지정된 IP에서 오는 웹훅 요청만 처리돼요. 서브넷 전체를 허용하려면 CIDR 표기법을 써요. 모든 IP를 허용하려면 비워 두세요.
Data structure 웹훅에 사용할 데이터 구조를 선택하거나 새로 만들어요. 이 구조로 들어오는 데이터를 검증하는데, 검증을 통과하지 못한 요청은 HTTP 상태 코드 400으로 거부돼요.
Get request headers 웹훅 요청에서 헤더 데이터를 추출해서 시나리오에서 매핑할 수 있게 해줘요.
Get request HTTP method 요청에서 HTTP 메서드를 추출해서 시나리오에서 매핑할 수 있게 해줘요.
JSON pass through JSON 페이로드를 매핑 가능한 필드로 쪼개는 대신, 텍스트 문자열 그대로 이후 모듈에 전달해요.

(이 웹훅 섹션은 커스텀 웹훅 모듈에서 만든 웹훅에만 적용돼요.)

커스텀 메일훅 모듈

**커스텀 메일훅(Custom mailhook)**은 이 모듈이 생성한 이메일 주소로 이메일을 보내면 트리거 되는 즉시 트리거 모듈이에요.

:::hint{type="info"} 메일훅으로 보내는 이메일의 최대 크기는 첨부 파일을 포함해 25 MB 예요. :::

예시로, 정기 실행 없이 들어오는 이메일을 계속 지켜보는 시나리오를 만들 수 있어요.

  1. 시나리오에 커스텀 메일훅 모듈을 추가해요. (Webhooks > Custom mailhook)
  2. Create a webhook 을 클릭해요. (선택)
  3. Webhook name 에 웹훅 이름을 입력해요.
  4. Save 를 클릭해요.
  5. 주소를 클립보드에 복사해요.
  6. Run once 로 시나리오를 저장하고 실행해요.

이메일 계정 설정에서 전달(forwarding) 을 구성하고, 위 2단계에서 만든 커스텀 메일훅 이메일 주소를 전달 주소로 사용해요. Gmail이라면 이렇게 해요.

  1. 오른쪽 상단의 톱니바퀴를 클릭하고 See all settings 를 클릭해요.
  2. Forwarding and POP/IMAP 탭을 열어요.
  3. Add a forwarding address 버튼을 클릭해요.
  4. 위 2단계에서 생성·복사한 이메일 주소를 입력하고 Next 를 클릭해요.
  5. 팝업 창이 뜨면 Proceed 를 클릭해요.
  6. 확인 링크가 메일훅으로 전송되었을 텐데, 커스텀 메일훅 모듈을 실행해 Bundle > text 에서 이 코드를 확인할 수 있어요. (직장이나 학교용 Gmail을 쓴다면 전달 주소를 인증할 필요가 없어요.)
  7. Enable forwarding 을 켜고 변경 사항을 저장해요.

나머지 원하는 모듈을 시나리오에 추가하고, 저장한 뒤 시나리오를 활성화해요. 이제 이메일 계정에 새 이메일이 도착할 때마다 시나리오 안의 커스텀 메일훅 모듈이 트리거 되고 이메일 메시지 데이터를 받아요. 발신자와 다양한 수신자 주소(To, Cc, Bcc)는 수신 메일의 데이터 구조에 담겨 오고, Reply-To는 헤더 섹션에서 찾을 수 있어요.

웹훅 응답 모듈

웹훅 호출에 대한 기본 응답은 "accepted"라는 단순한 텍스트예요. 이 응답은 커스텀 웹훅 모듈 실행 중에 웹훅을 호출한 쪽에 바로 반환돼요. 간단히 이렇게 테스트할 수 있어요.

  1. 시나리오에 커스텀 웹훅 모듈을 배치해요.
  2. 모듈 설정에서 웹훅을 새로 추가해요.
  3. 웹훅 URL을 클립보드에 복사해요.
  4. 시나리오를 실행해요. 커스텀 웹훅 모듈이 웹훅 호출을 기다리는 상태가 돼요. (오른쪽에서 확인 가능)
  5. 새 브라우저 창을 열고, 복사한 URL을 주소창에 붙여 넣고 Enter 를 눌러요.
  6. 커스텀 웹훅 모듈이 트리거 되고, 브라우저에 다음 페이지가 표시돼요.

시나리오에 웹훅 응답(Webhook response) 모듈이 없을 때의 기본 응답은 이래요.

HTTP 상태 코드 본문
Webhook accepted in the queue 200
accepted 200
Webhook queue full 400
queue is full 400

웹훅의 응답을 커스터마이즈하고 싶다면 웹훅 응답 모듈을 쓰면 돼요. 모듈 설정에는 status와 body라는 두 필드가 있어요.

  • status 필드에는 HTTP 응답 상태 코드가 들어가요. (참고: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) 성공은 2xx(예: 200 OK), 리다이렉션은 3xx(예: 307 Temporary Redirect), 클라이언트 오류는 4xx(예: 400 Bad Request)처럼 써요.
  • body 필드에는 웹훅 호출자에게 보낼 내용이 들어가요. 단순 텍스트, HTML, XML, JSON 등 무엇이든 될 수 있어요.

Content-Type 헤더를 해당 MIME 타입으로 맞춰 주는 게 좋아요. (참고: https://en.wikipedia.org/wiki/Media_type) plain text는 text/plain, HTML은 text/html, JSON은 application/json, XML은 application/xml 등이에요.

시나리오에 웹훅 응답 모듈이 있을 때의 추가 기본 응답은 이래요.

HTTP 상태 코드 본문
500 encounters an error: failed to complete

응답을 보내는 데 걸리는 제한 시간은 180초예요. 이 시간 안에 응답이 준비되지 않으면 Make가 '200 accepted' 상태를 반환해요.

HTML 응답 예시

웹훅 응답 모듈을 이렇게 설정해요.

설정 값
status 2xx 성공 상태 코드(예: 200)
body HTML 코드, 예: <!doctype html><html lang="en"><head><meta charset="utf-8"><title>Thank you!</title></head><body>Thank you, {{1.name}}, for your request!</body></html>
custom headers key: content-type, value: text/html

그러면 웹 브라우저에 이렇게 표시되는 HTML 응답이 만들어져요.

리다이렉트 예시

웹훅 응답 모듈을 이렇게 설정해요.

설정 값
status 3xx 리다이렉션 상태 코드(예: 303)
custom headers key: location, value: 리다이렉트할 URL

트러블슈팅

웹훅을 다루다 보면 나중에 모듈에서 매핑하고 싶었던 데이터 값이 일부 빠져 있는 문제를 흔히 겪어요. 새 값을 추가하려면 커스텀 웹훅 모듈에서 데이터 구조를 다시 결정(re-determine)하면 돼요.

  1. 빌더에서 Webhooks > Custom webhook 모듈을 열어요.
  2. Detect new values 를 클릭해요.
  3. 서드파티 서비스에서 웹훅 URL로 샘플 데이터를 담은 요청을 보내요.

그러면 데이터 구조가 다시 결정되고, 새로 감지된 데이터 값들을 이후 모듈에서 매핑할 수 있게 돼요.

더 알아보기