웹훅 액션(API 호출)

가입한 분의 정보를 사내 시스템에 전달하거나, 구매가 끝나면 외부 서비스에 알림을 보내고 싶을 때가 있습니다. 자동화 빌더의 웹훅 액션은 연락처가 해당 단계에 도착했을 때 내가 정한 외부 주소로 HTTP 요청을 보내 줍니다. 이 글에서는 웹훅 액션을 추가하고, 주소·메소드·헤더·바디·인증을 설정하는 방법을 안내합니다.

1. 어디에 있나요

자동화 빌더에서 블록 사이의 더하기 버튼을 누르면 오른쪽에 액션 선택 패널이 열립니다. 목록 중간쯤에 웹훅(API 호출) 카드가 있습니다. 카드를 누르면 블록이 추가되고 속성 패널이 열립니다. 블록의 기본 이름은 웹훅 호출입니다.

외부 시스템이 퍼널체인저스의 자동화를 시작시키는 웹훅 트리거와는 방향이 반대입니다. 트리거는 별도 글에서 다루고, 이 글의 액션은 자동화가 바깥으로 요청을 보내는 단계입니다.

2. 설정하는 방법

속성 패널의 위쪽에는 모든 액션이 공통으로 쓰는 레이블과 설명이 있습니다. 설명을 적어 두면 캔버스의 블록 부제로 표시되어 어떤 용도의 웹훅인지 한눈에 알 수 있습니다.

1. 보낼 주소 (URL)에 요청을 받을 외부 주소를 입력합니다. http 또는 https 주소를 쓰며, 내부망·사설 주소로는 보낼 수 없습니다.
2. HTTP 메소드에서 POST, GET, PUT, PATCH, DELETE 중 하나를 고릅니다. 기본값은 POST입니다.
3. 헤더 (JSON)에 추가할 헤더를 JSON 형식으로 적습니다. 비워 두어도 요청에는 Content-Type: application/json 헤더가 기본으로 붙습니다.
4. 바디 (JSON)에 보낼 내용을 JSON 형식으로 적습니다.
5. 패널 아래 저장을 누르면 설정이 자동화에 저장됩니다.

3. 연락처 정보를 바디에 넣기

바디의 값에는 사용 가능한 변수로 안내된 항목을 넣을 수 있습니다. 변수 이름을 중괄호 두 겹으로 감싸 쓰면, 실행될 때 해당 연락처의 실제 값으로 바뀌어 전송됩니다. 패널에 나오는 변수는 다음과 같습니다.

• 연락처: customer.id(번호), customer.email(이메일), customer.phone(전화번호), customer.name(이름)
• 자동화: automation.id(자동화 번호), execution.id(이번 실행 번호), timestamp(실행 시각)

위 화면의 바디는 연락처 번호·이메일·이름과 실행 번호를 JSON으로 묶어 보내는 예입니다. 보낼 주소에도 같은 변수를 쓸 수 있습니다.

4. 인증 방식 고르기

받는 쪽에서 인증을 요구하면 패널 맨 아래 인증에서 방식을 고릅니다.

• 없음: 인증 없이 보냅니다.
• Bearer Token: Bearer Token 칸에 입력한 토큰이 요청의 인증 헤더로 전달됩니다.
• Basic Auth: 사용자명과 비밀번호 칸에 입력한 값으로 기본 인증이 이루어집니다.

토큰과 비밀번호는 외부 서비스에서 발급받은 값을 그대로 입력하며, 화면을 캡처해 공유할 때는 노출되지 않게 주의해 주세요.

5. 실행될 때의 동작

연락처가 웹훅 블록에 도착하면 설정한 주소로 요청이 한 번 전송됩니다. 받는 쪽이 성공 응답(2xx)을 주면 성공으로, 그 밖의 응답이나 연결 실패는 실패로 실행 기록에 남습니다. 웹훅이 실패해도 자동화는 멈추지 않고 다음 블록으로 이어집니다. 응답을 기다리는 시간은 최대 30초이고, 받는 쪽이 다른 주소로 안내(리다이렉트)하더라도 따라가지 않습니다.

6. 이렇게 활용해 보세요

• 가입 정보를 사내 시스템에 전달하기: 가입 이벤트를 트리거로 두고 웹훅으로 연락처 정보를 보내 보세요.
• 외부 서비스에 알림 보내기: 구매 완료 뒤에 웹훅으로 메신저·업무 도구의 수신 주소를 호출해 담당자에게 알릴 수 있습니다.
• 실행 번호로 추적하기: 바디에 execution.id를 함께 보내면 받는 쪽에서 어떤 실행에서 온 요청인지 구분할 수 있습니다.

7. 알아 두실 점

• 보낼 주소를 꼭 입력해 주세요: 주소가 비어 있으면 요청이 전송되지 않고 실패로 기록됩니다.
• 내부망 주소는 막혀 있습니다: 사설 IP, localhost 같은 내부 주소로는 보낼 수 없으니 외부에서 접근 가능한 주소를 사용해 주세요.
• JSON 형식을 지켜 주세요: 헤더와 바디는 따옴표와 중괄호가 맞는 JSON으로 입력합니다.
• 실제 실행되는 외부 호출입니다: 자동화를 활성화하면 연락처마다 요청이 전송되므로, 처음에는 받는 쪽을 확인할 수 있는 주소로 시험해 보시기 바랍니다.
• 저장해야 반영됩니다: 속성 패널에서 값을 바꾼 뒤에는 패널 아래 저장을 눌러 주세요.

빌더의 기본 조작과 다른 액션은 별도 글에서 이어서 안내합니다.